Sites (.sites.json)

This document describes BeamNG .sites.json files.

Sites files store gameplay-relevant spatial metadata such as:

• Locations
• Zones
• Parking spots
• Tags
• Custom fields

They are used by gameplay systems, missions, traffic, parking logic, facilities, POIs, and editor tools to understand named points and areas of a level.

Overview

A .sites.json file defines named spatial data. Unlike normal scene objects, sites are not rendered as level geometry. Instead, they describe useful gameplay positions, areas, and parking locations.

Common uses include:

• Mission start and finish locations
• Named city districts or map regions
• Facility zones, such as garages or dealerships
• Parking spot placement
• Vehicle spawn areas
• Delivery/drop-off zones
• Gameplay zone filtering
• Metadata for traffic, parking, and procedural missions
• Mission boundaries

Sites are usually edited with:

World Editor → Gameplay → Sites Editor

File locations

Sites files use the suffix:

*.sites.json

Common examples:

levels/<levelName>/city.sites.json
levels/<levelName>/facilities.sites.json
levels/<levelName>/garages.sites.json
gameplay/missions/<levelName>/<missionType>/<missionName>/bounds.sites.json
/gameplay/*.sites.json

The sites manager can scan .sites.json files inside level folders and under:

/gameplay/

This allows both level-specific and shared gameplay sites.

Common sites files

Default level sites file

When a level starts, gameplay systems usually try to load the default sites file for the current map:

<level folder>/city.sites.json

For example:

levels/west_coast_usa/city.sites.json

If the file exists, it is loaded and cached by the sites manager.

This default file is commonly used by systems such as:

• City/level metadata helpers
• Parking
• Random parking spot selection
• Zone lookup by position
• Vehicle group metadata
• Mission and gameplay utilities

Other sites file examples

facilities.sites.json

Facilities are usually defined in info.json or *.facilities.json files, but those facility definitions often reference zones or parking spots stored in a .sites.json file.

For example, a garage facility may reference:

"sitesFile": "facilities.sites.json",
"zoneNames": ["garage_downtown"],
"parkingSpotNames": ["garage_downtown_01", "garage_downtown_02"]

The sites file contains the actual zone and parking spot data.

garages.sites.json

Some gameplay/career systems load a sites file from a configured folder, commonly:

garages.sites.json

This is used to populate lists of garage-related zones. For example, tools may load all zone names from this file so designers can select valid initial and destination garage zones.

bounds.sites.json

Some mission data uses a bounds.sites.json file to store mission boundaries.

A mission porting workflow may convert:

bounds.sites.json

into a newer boundary format.

In this case, the sites file usually contains one or more zones, and the first zone may be used as the mission boundary.

Main data types

A sites file can contain three main spatial element types:

Each type can also have:

• Name
• Sort order
• Tags
• Custom fields

Locations

Locations are named points or small spatial markers.

They are useful for:

• Mission start points
• Mission finish points
• Landmarks
• Delivery points
• AI/navigation references
• Camera or gameplay reference points

A location usually stores:

Example location names:

gas_station
police_station
industrial_delivery_01
race_start

Zones

Zones define named areas of the map.

They are commonly used for:

• Districts
• Mission boundaries
• Facility areas
• Garage/dealership areas
• Delivery zones
• Vehicle group filtering
• Parking spot grouping
• Spawn region logic
• Gameplay area checks

Gameplay code can query zones containing a position, for example:

getZonesForPosition(pos)

Zones are especially useful when a system needs to know “where” something is, not just the nearest point.

Zone boundaries

Zones are polygon-like areas made from vertices. Some zone data can also include vertical limits such as top and bottom planes.

A conceptual zone may contain:

{
  "name": "downtown",
  "vertices": [
    {"pos": [0, 0, 0]},
    {"pos": [100, 0, 0]},
    {"pos": [100, 100, 0]},
    {"pos": [0, 100, 0]}
  ],
  "top": {
    "active": false,
    "pos": [0, 0, 10],
    "normal": [0, 0, 1]
  },
  "bot": {
    "active": false,
    "pos": [0, 0, -10],
    "normal": [0, 0, -1]
  }
}

Zone priority

Zones can use a custom field named:

priority

Higher priority zones are preferred when multiple zones contain the same position.

Example:

"customFields": {
  "priority": 10
}

This is useful when a smaller, more specific area exists inside a larger general zone.

Example:

City
 └── Downtown
      └── Dealership

If all three zones contain the same position, systems can select the highest-priority zone.

Zone custom fields

Zones can store gameplay metadata in custom fields.

A commonly used field is:

vehicleGroup

The system also supports suffixes for multiple entries:

vehicleGroup
vehicleGroup1
vehicleGroup2
vehicleGroup3
vehicleGroup4

This allows one zone to reference several vehicle groups or metadata entries.

Example:

"customFields": {
  "priority": 5,
  "vehicleGroup": "city",
  "vehicleGroup1": "traffic",
  "vehicleGroup2": "parked"
}

Gameplay code can merge these fields from the highest-priority matching zones.

Parking spots

Parking spots define vehicle placement locations.

They are used for:

• Parked traffic
• Mission vehicle spawns
• Garage quick travel
• Delivery destinations
• Scenario start/end positions
• Random parking spot selection
• Parking validation

A parking spot usually stores:

Parking spots can be associated with zones. For example, a parking spot inside a zone can inherit district, facility, or gameplay metadata from that zone.

Parking spot tags

Parking spots may use tags to control parking behavior.

Common tags include:

These are mostly used by dynamic parking and traffic systems.

Parking spot custom fields

Parking spots can use custom fields such as:

probability

Example:

"customFields": {
  "probability": 0.5
}

This controls how likely a spot is to be used by systems that scatter parked vehicles.

The parking system may also adjust probability by time of day using tags like nightTime and dayTime.

Random parking spot selection

Gameplay utilities can select random parking spot pairs.

For example, one function can return:

start parking spot
destination parking spot
start zone
destination zone

with a minimum distance between start and destination.

This is useful for:

• Procedural missions
• Delivery routes
• Random driving tasks
• Career gameplay

Tags

Sites support tags for:

• Locations
• Zones
• Parking spots

Tags are used for filtering and organization.

Example tags:

delivery
garage
fuel
parking
industrial
urban
offroad
race
banned
street
nightTime
dayTime

The Sites Editor has separate tabs for:

• Location Tags
• Zone Tags
• Parking Spot Tags

Custom fields

Custom fields allow gameplay systems to attach arbitrary metadata to sites.

Examples:

"customFields": {
  "priority": 10,
  "vehicleGroup": "traffic_city",
  "missionType": "delivery",
  "difficulty": "easy",
  "probability": 0.75
}

Custom fields are commonly used by systems that need map-specific data without hardcoding it into scripts.

Facilities and sites

Facilities use sites files to resolve spatial data.

Facility definitions may reference:

"sitesFile": "facilities.sites.json",
"zoneNames": ["dealership_downtown"],
"parkingSpotNames": ["dealership_downtown_01"]

Then the facility system loads those sites files and looks up:

• Zones by name
• Parking spots by name

This is used for:

• Garages
• Gas stations
• Dealerships
• Computers
• Private sellers
• Delivery providers
• Dragstrips

Mission boundaries

Some older mission formats store boundaries in:

bounds.sites.json

These files usually contain zones representing the playable/mission area.

Mission conversion tools can convert this data into newer boundary/path/trail files.

Typical conversion:

bounds.sites.json → boundary file
race.race.json → path file
race.race.json startPositions → starting position file

Sites Editor

The Sites Editor is available in the World Editor:

World Editor → Gameplay → Sites Editor

The editor provides tabs for:

• Locations
• Zones
• Parking Spots
• Location Tags
• Zone Tags
• Parking Spot Tags

It can:

• Create new sites files
• Load existing .sites.json files
• Save sites files
• Sort locations by name
• Sort zones by name
• Sort parking spots by name
• Enumerate duplicate parking spot names
• Rename parking spots based on containing zone

Saving

When saving from the Sites Editor, the file path is stored in the sites object:

sites.dir
sites.name

The file is written as JSON using:

jsonWriteFile(path, data, true)

Use the editor to save whenever possible, as it ensures the serialized structure matches what the gameplay sites system expects.

Loading and caching

The sites manager loads sites files through:

gameplay_sites_sitesManager.loadSites(filepath)

Loaded files are cached by path. If the same file is requested again, the cached sites object is reused unless forced reload is requested.

The cache is cleared when the mission ends.

Manager discovery

The sites manager can scan all levels for .sites.json files.

It stores a list of sites files per level:

sitesByLevel[levelName] = { ... }

The Sites Editor can display these through:

File → Sites in Manager...

This makes it easier to find and load sites files from other levels or from /gameplay.

Simplified structure

The exact serialized structure is generated by the gameplay sites system, but conceptually a sites file contains:

{
  "name": "city",
  "locations": [],
  "zones": [],
  "parkingSpots": [],
  "tags": {},
  "customFields": {}
}

A simplified conceptual example:

{
  "name": "city",
  "locations": [
    {
      "name": "gas_station",
      "pos": [100, 200, 0],
      "radius": 10,
      "tags": ["fuel", "service"]
    }
  ],
  "zones": [
    {
      "name": "downtown",
      "vertices": [
        {"pos": [0, 0, 0]},
        {"pos": [100, 0, 0]},
        {"pos": [100, 100, 0]},
        {"pos": [0, 100, 0]}
      ],
      "customFields": {
        "priority": 5,
        "vehicleGroup": "city"
      }
    }
  ],
  "parkingSpots": [
    {
      "name": "downtown_parking_01",
      "pos": [50, 50, 0],
      "rot": [0, 0, 0, 1],
      "scl": [2.5, 5.5, 1],
      "tags": ["parking", "street"],
      "customFields": {
        "probability": 0.75
      }
    }
  ]
}

Recommended workflow

1. Open the World Editor.
2. Open Gameplay → Sites Editor.
3. Create or load a .sites.json file.
4. Add locations, zones, and parking spots.
5. Add tags and custom fields where needed.
6. Use sorting/enumeration tools to keep data organized.
7. Save as the appropriate file:
   • city.sites.json for default level sites
   • facilities.sites.json for facility spatial data
   • garages.sites.json for garage/career zone data
   • bounds.sites.json for mission boundary data when needed

Naming recommendations

Use clear and stable names.

Good examples:

downtown
industrial_zone
gas_station_01
garage_downtown
parking_downtown_001
delivery_port_03
race_start_city

Avoid:

test
new
zone1
asdf
parking

Parking spots often benefit from numbered names:

parking_downtown_001
parking_downtown_002
parking_downtown_003

The editor includes an Enumerate Parking Spots tool for duplicate names.

Best practices

• Use city.sites.json for the default level sites file.
• Use separate sites files for specialized data when appropriate, such as facilities.sites.json or garages.sites.json.
• Use zones for large named areas.
• Use locations for specific points of interest.
• Use parking spots for vehicle placement.
• Use tags for filtering.
• Use custom fields for gameplay metadata.
• Use priority on overlapping zones.
• Keep names stable once missions, facilities, or career data depend on them.
• Use the Sites Editor instead of manual editing when possible.
• Save and test after major edits.
• Avoid deleting or renaming zones/parking spots that are referenced by other files.

Common issues

Sites file does not load

Possible causes:

• File does not exist
• Invalid JSON
• Wrong file extension
• File is not named *.sites.json
• File is not in the expected level/gameplay path

Default sites are not loaded

Check that the level contains:

city.sites.json

in the level folder.

Facility zone or parking spot is missing

Possible causes:

• Facility references the wrong sitesFile
• zoneNames do not match zone names in the sites file
• parkingSpotNames do not match parking spot names in the sites file
• Sites file path is wrong

Parking spot is not found

Possible causes:

• Parking spot name changed
• File not loaded
• Parking spot removed
• Tags or custom fields do not match expected filters
• Parking spot is tagged banned

Parked cars do not spawn in expected spots

Check:

banned
probability
dayTime
nightTime
street
perfect
forwards
backwards

Also check that the vehicle fits inside the parking spot bounds.

Zone priority does not work as expected

Check the zone custom field:

priority

It should be numeric.

Vehicle group data is missing

Check for zone custom fields:

vehicleGroup
vehicleGroup1
vehicleGroup2
vehicleGroup3
vehicleGroup4

Parking spots have duplicate names

Use:

Tools → Enumerate Parking Spots

in the Sites Editor.

Summary

.sites.json files store gameplay map metadata.

They define:

• Locations
• Zones
• Parking spots
• Tags
• Custom fields

The default level sites file is usually:

city.sites.json

Other common examples include:

facilities.sites.json
garages.sites.json
bounds.sites.json

Sites are used by gameplay systems to find named places, determine zones by position, select parking spots, support facilities, and apply map-specific metadata such as vehicle groups and priorities.