Level Gameplay Data

Level gameplay data is the layer that connects a level’s scene, roads, sites, traffic, missions, POIs, and map UI. Most of these systems already have dedicated format or class pages. This page is a high-level integration guide: use it to understand which systems depend on each other and where to continue reading.

For field-level reference, use the dedicated pages instead of this overview:

• Level metadata (info.json)
• Sites (.sites.json)
• Navigation map (map.json)
• Traffic signals (signals.json)
• Bus lines (*.buslines.json)
• Facilities (*.facilities.json)
• Vehicle groups (*.vehGroup.json)
• Drift spots (driftSpots/)
• Crawls (crawls/)
• Drag strips (dragstrips/)
• DecalRoad
• BeamNGWaypoint
• BeamNGTrigger
• Gameplay Areas and Points of Interest
• Speedtraps
• Fuel Stations

How the pieces fit

Gameplay features usually combine several kinds of data:

Treat these as connected data, not independent files. A mission may start from gameplay/missions/, use path data from race.race.json, query sites from the level, route over the navgraph, show a marker through the POI system, and depend on scene triggers or waypoints.

Common level-side feature folders

A gameplay-heavy level may include some of these folders or files:

levels/<levelName>/
+-- buslines/
+-- crawls/
+-- dragstrips/
+-- driftSpots/
+-- facilities/
+-- quickrace/
+-- scenarios/
+-- camPaths/
+-- city.sites.json
+-- facilities.sites.json
+-- map.json
+-- signals.json
+-- triggers.json
+-- *.vehGroup.json

Not every level needs all of them. Small sandbox or test levels may only need info.json, a scene tree, spawn points, and simple road/navgraph data.

Facilities and sites

Facilities give gameplay meaning to places such as garages, gas stations, dealerships, computers, delivery providers, private sellers, and drag strips. Their spatial data is usually supplied by sites and scene objects rather than being duplicated in the facility entry.

Use the existing pages for details:

• Facilities (*.facilities.json) for the general facility file format.
• Sites (.sites.json) for zones, parking spots, boundaries, and named locations.
• Fuel Stations for gas station and charging station setup.
• Gameplay Areas and Points of Interest for interaction areas and POI objects.

When something facility-related does not appear in freeroam, career, or the big map, check the chain in this order: facility entry, referenced sites file, referenced zone/parking names, referenced scene objects, and POI provider behavior.

Bus routes

Bus route data lives in buslines/, but the route usually depends on more than the JSON file. A route may require scene bus stop objects or triggers, valid stop ids, route helper nodes, and a connected navgraph.

Keep bus route names, stop ids, and waypoint names stable after missions or UI reference them. For format details, see Bus Lines (*.buslines.json) . For trigger object behavior, see BeamNGTrigger .

Drift, crawl, and drag gameplay

These feature folders are level-local gameplay data. They often pair feature-specific files with shared systems such as sites, navgraph routes, scene markers, facilities, and missions.

See Drift Spots , Crawls , and Drag Strips for the folder/file references.

Traffic authoring

Traffic is a combined result of:

• Level metadata such as traffic support, region, and road rules in info.json
• Drivable roads and waypoints in the scene
• Manual navgraph corrections in map.json
• Parking and zone data in .sites.json
• Traffic signal data in signals.json
• Optional level vehicle groups such as traffic.vehGroup.json or police.vehGroup.json
• Feature objects such as speed traps or red-light camera triggers

Use Navigation map (map.json) for graph corrections, Traffic Signals (signals.json) for signal data, DecalRoad for road fields, and Speedtraps for camera setup.

Use Vehicle Groups (*.vehGroup.json) for shared, level-specific, or mission-specific vehicle pools.

After editing roads, waypoints, map segments, signals, or traffic-related sites, reload the navgraph and test with live traffic. The same graph is also used by route previews, missions, bus routes, and map UI, so traffic problems often point to a shared graph issue.

Missions and Flowgraph

Modern missions usually live outside the level folder:

gameplay/missions/<levelName>/<missionType>/<missionName>/

Mission folders commonly connect to level data:

Mission types such as busMode, crawl, drift, dragStripRace, delivery, garageToGarage, timeTrial, aiRace, rallyStage, and flowgraph each consume different combinations of this data. When a mission appears in the UI but behaves incorrectly, check the mission folder first, then the level systems it references.

Legacy content under levels/<levelName>/scenarios/ is separate from modern gameplay/missions/. Some levels still contain both.

POIs and map UI

POIs are not owned by one required level file. The big map aggregates POIs from spawn metadata, missions, facilities, gas stations, drift spots, crawls, drag strips, parking/sites, and scene BeamNGPointOfInterest objects.

The optional levels/<levelName>/pois/ folder may be used by tools, but it is not the only POI source. When a marker is missing, identify the owning feature first, then check that feature’s references.

The minimap and big map also use the navgraph. A minimap image layer can be valid while route generation is broken, and route generation can work while a minimap image is missing. Check info.json minimap references separately from roads, waypoints, and map.json.

Other level gameplay and presentation data

Some level folders are feature-specific and should stay out of the main file-format pages unless they get a dedicated schema reference:

Use these as integration points. If a feature has its own authoring page, keep detailed setup there and link to it from this overview.

Clean authoring order

For a new gameplay-heavy level, this order keeps dependencies manageable:

1. Create roads, waypoints, spawns, and required scene objects.
2. Set up info.json metadata, spawn entries, traffic support, road rules, and minimap references.
3. Build and test the navgraph with roads, waypoints, and map.json.
4. Add sites for parking, zones, facilities, boundaries, and named locations.
5. Add facilities, POIs, bus routes, drift/crawl/drag data, quickrace, or other feature folders.
6. Add missions and connect them to paths, sites, Flowgraphs, and scene objects.
7. Add traffic signals, speed traps, vehicle groups, and traffic tuning.
8. Test in freeroam, traffic, mission UI, big map, minimap, and any feature-specific editor.

Validation checklist

Before shipping level gameplay data, check:

• Referenced object, site, waypoint, route, trigger, POI, and facility names exist.
• JSON files load without parse errors.
• The navgraph is reloaded after road, waypoint, map.json, signal, or site edits.
• Traffic can spawn, route, and respond to signals where expected.
• Bus routes, missions, and quickrace content can resolve their path and stop references.
• Facilities resolve their sites, parking spots, gameplay areas, and POIs.
• Speed traps and red-light cameras are validated through the dedicated speedtrap workflow.
• The minimap and big map show expected routes, POIs, and spawn points.
• Legacy scenarios and modern missions are not confused for each other.

Related pages

• Level File Formats
• Level Object Classes
• World Editor
• Facilities
• Vehicle Groups
• Drift Spots
• Crawls
• Drag Strips
• Fuel Stations
• Speedtraps