Bus Lines (*.buslines.json)

This document describes BeamNG bus line JSON files used by levels.

Bus line files define bus routes, route variants, stop order, navigation helpers, route preview images, and bus spawn data.

File location

Bus line files are usually stored under:

levels/<levelName>/buslines/*.buslines.json

Examples:

levels/west_coast_usa/buslines/wca.buslines.json
levels/italy/buslines/italy.buslines.json
levels/GridMap/buslines/gridmap.buslines.json

Basic structure

{
  "version": 1,
  "routes": [
    {
      "routeID": "1",
      "variance": "a",
      "name": "levels.example.buslines.routes.1a",
      "direction": "Downtown",
      "routeColor": "#3b9c00",
      "vehicle": {
        "model": "citybus",
        "config": "base"
      },
      "tasklist": [
        "bus_stop_01",
        "bus_stop_02",
        "bus_stop_03"
      ],
      "spawnLocation": {
        "pos": { "x": 0, "y": 0, "z": 0 },
        "rotAngAxisF": { "x": 0, "y": 0, "z": 1, "w": 90 }
      }
    }
  ]
}

Top-level fields

Field	Type	Description
`version`	integer	Bus line format version.
`routes`	array	List of route definitions.

Route fields

Field	Type	Description
`routeID`	string	Route number/id. Variants can share the same route id.
`variance`	string	Route variant, such as `"a"` or `"b"`.
`name`	string	Translation key or display name for the route.
`direction`	string	Translation key or display text for route direction/destination.
`routeColor`	string	Hex color used for UI/route display.
`vehicle`	object	Optional bus vehicle model/config.
`tasklist`	array[string]	Ordered list of bus stop/task ids.
`spawnLocation`	object	Optional initial bus spawn position and rotation.
`requiredWaypoints`	object	Required waypoint checks for route sections.
`navhelp`	object	Extra navigation waypoint hints between bus stops.
`previews`	array[string]	Preview image names for route UI.

tasklist

tasklist defines the ordered bus stops/tasks for a route.

"tasklist": [
  "bus_stop_01",
  "bus_stop_02",
  "bus_stop_03"
]

The ids in this list must match the bus stop/task definitions used by the bus route gameplay system.

Many shipped levels pair busline entries with BeamNGTrigger bus-stop objects and navigation data.

navhelp

navhelp provides extra navigation path hints for route sections.

"navhelp": {
  "bus_stop_02": ["wp_main_01", "Bridge_A", "Bridge_B"]
}

Values usually reference navigation node names from BeamNGWaypoint, DecalRoad generated nodes, or map.json segments.

requiredWaypoints

requiredWaypoints can require the route to pass through specific waypoints.

"requiredWaypoints": {
  "bus_stop_03": {
    "wp": ["checkpoint_01"],
    "failmsg": "You got too far-off the route"
  }
}

This is useful where a route must stay on a specific road or connector.

spawnLocation

spawnLocation defines where the bus starts.

"spawnLocation": {
  "pos": { "x": -337.572, "y": 605.564, "z": 75.0979 },
  "rotAngAxisF": { "x": 0, "y": 0, "z": 1, "w": 135.337 }
}

rotAngAxisF.w is the rotation angle in degrees around the axis.

Tool notes

For tools that edit bus lines:

Keep routeID and variance stable for existing routes.
Validate every tasklist stop id.
Validate waypoint names used by navhelp and requiredWaypoints.
Preserve translation keys in name and direction if the route is localized.
Keep preview image paths/names consistent with the route UI.

Common issues

Route fails because a bus stop id in tasklist does not exist.
Navigation sends the bus the wrong way because navhelp references missing or wrong waypoint names.
Route UI has missing text because name or direction points to a missing translation key.
Bus spawns facing the wrong direction because rotAngAxisF is wrong.

Validation criteria

Bus line JSON parses correctly.
Every route has a stable routeID, variance, name, and tasklist.
Stop ids and waypoint names resolve.
Spawn location is safe for the configured vehicle.
The route can be driven end-to-end in game.