Level Metadata (info.json)

This document describes the info.json file used by BeamNG levels.

info.json is the main metadata file for a level. It is used by the level selector, loading logic, spawn point UI, big map/POI systems, environment presets, traffic/gameplay systems, minimap display, and some region-specific gameplay logic.

It does not store level geometry. Scene objects are stored separately in files such as main/items.level.json.

File location

Each level should contain an info.json file in the level root folder:

levels/<levelName>/info.json

Example:

levels/west_coast_usa/info.json

If info.json is missing, the level may still be detected if it has a valid entry point, but UI metadata will be incomplete and warnings may be logged.

Level discovery

The level manager scans:

/levels/

Each directory is treated as a potential level.

A level is considered usable if the loader can find a valid entry point. The current preferred format is the main/ scene tree folder:

levels/<levelName>/main/

Older entry points such as .mis files or .level.json files may still be handled for compatibility, but modern levels should use the main/ folder layout.

During discovery, the loader reads info.json, adds runtime metadata, resolves preview paths, processes spawn point data, and applies defaults for missing optional fields.

Basic structure

A simplified info.json file:

{
  "title": "levels.example.info.title",
  "description": "levels.example.info.description",
  "authors": "BeamNG",
  "defaultSpawnPointName": "spawns_default",
  "country": "levels.common.country.usa",
  "region": "northAmerica",
  "size": [2048, 2048],
  "previews": [
    "preview.jpg"
  ],
  "spawnPoints": [
    {
      "translationId": "levels.example.spawnpoints.default",
      "description": "levels.example.spawnpoints.default.description",
      "objectname": "spawns_default",
      "preview": "spawns_default.jpg"
    }
  ]
}

Common fields

Translation IDs

Most user-facing text fields should use translation IDs instead of hardcoded display text.

Example:

"title": "levels.west_coast_usa.info.title",
"description": "levels.west_coast_usa.info.description"

This allows the UI to localize level names, descriptions, spawn point names, and other text.

Common translated fields include:

• title
• description
• features
• suitablefor
• roads
• biome
• country
• spawnPoints[].translationId
• spawnPoints[].description
• spawnPoints[].logbookEntry

Preview images

The previews array defines level preview images.

"previews": [
  "spawns_industrial.jpg",
  "west_coast_usa_preview1.jpg",
  "west_coast_usa_preview2.jpg"
]

Paths are relative to the level folder. During loading, they are converted to full virtual paths.

Example:

"west_coast_usa_preview1.jpg"

becomes:

/levels/west_coast_usa/west_coast_usa_preview1.jpg

The first preview image is generally used as the main level thumbnail.

If previews is missing or empty, fallback preview paths are attempted from the level entry point.

Spawn points

The spawnPoints array defines spawn choices shown in the UI and big map.

Example:

"spawnPoints": [
  {
    "translationId": "levels.west_coast_usa.spawnpoints.industrial",
    "description": "levels.west_coast_usa.spawnpoints.industrial.description",
    "logbookEntry": "levels.west_coast_usa.spawnpoints.industrial.logbookEntry",
    "objectname": "spawns_industrial",
    "preview": "spawns_industrial.jpg"
  }
]

Spawn point fields

The objectname should match an object in the level, usually a SpawnSphere.

Example scene object:

{"class":"SpawnSphere","name":"spawns_industrial","position":[0,0,1],"rotationMatrix":[1,0,0,0,1,0,0,0,1]}

Default spawn point

The default spawn point is selected using:

"defaultSpawnPointName": "spawns_industrial"

This should match one of the spawnPoints[].objectname values.

When a spawn point matches defaultSpawnPointName, it is marked internally as the default spawn and receives the level’s main preview list.

If no matching spawn point is found, the loader inserts a fallback default spawn entry using the level preview images.

Spawn point POIs

Spawn points can be exposed as POIs in the big map.

For each spawn point with an objectname, the system looks up the matching scene object and uses its position as the marker position.

If the object cannot be found, an error may be logged.

Minimap

The minimap array defines one or more minimap image tiles.

Example:

"minimap": [
  {
    "file": "minimap/terrain.png",
    "size": [2048, 2048],
    "offset": [-1024, 1024]
  },
  {
    "file": "minimap/island.png",
    "size": [4096, 2048],
    "offset": [-1536, 3072]
  }
]

Minimap fields

During loading, file is prefixed with the level directory.

Example:

minimap/terrain.png

becomes:

/levels/west_coast_usa/minimap/terrain.png

Road rules

The roadRules object stores level-specific driving rules used by navigation, AI, and traffic-related systems.

Example:

"roadRules": {
  "rightHandDrive": false,
  "turnOnRed": true
}

If roadRules is missing, the default values are:

{
  "rightHandDrive": false,
  "turnOnRed": false
}

Supported road rule fields

rightHandDrive

rightHandDrive affects how the navigation graph interprets/generated lane directions.

Internally, lane directions are represented with strings:

+ = lane direction from inNode to outNode
- = lane direction from outNode to inNode

For two-way roads, the lane order depends on whether the level uses right-side or left-side traffic.

Use:

"rightHandDrive": false

for regions with right-side traffic.

Use:

"rightHandDrive": true

for regions with left-side traffic.

Local units

The localUnits object defines level-specific unit preferences used by gameplay/UI systems.

Example:

"localUnits": {
  "gasoline": "gallonUS",
  "diesel": "gallonUS"
}

This is currently used by systems such as fuel price display logic. Internally, prices may be stored in metric units, while display objects can convert values depending on the level’s local unit settings.

For example:

"gasoline": "gallonUS"

allows gasoline price signage to use US gallon-style display.

Supported fuel unit example

If no local unit override is provided, systems use their default behavior.

Traffic support

If supportsTraffic is missing, it defaults to:

"supportsTraffic": true

Set it to false if the level should not expose traffic-related systems.

Example:

"supportsTraffic": false

Time-of-day support

If supportsTimeOfDay is missing, it defaults to:

"supportsTimeOfDay": true

Set it to false if the level should not expose time-of-day options.

Example:

"supportsTimeOfDay": false

Time-of-day presets

Levels can define custom time-of-day presets.

Example:

"timeOfDayPresets": [
  {
    "key": "sunrise",
    "value": 0.23,
    "label": "ui.environment.time.sunrise"
  },
  {
    "key": "noon",
    "value": 0.5,
    "label": "ui.environment.time.noon"
  }
]

Preset fields

By default, the game starts with common time-of-day presets and then applies/overrides level-specific presets.

To exclude default presets:

"excludeDefaultTimeOfDayOptions": true

If this is set, provide your own timeOfDayPresets or the level may have no selectable time-of-day options.

Auxiliary levels

Older metadata may use:

"hidden": true

This field is deprecated.

Use:

"isAuxiliary": true

If hidden is found, the loader maps it to isAuxiliary for compatibility and logs a warning.

Full example

{
  "features": "levels.example.info.features",
  "suitablefor": "levels.example.info.suitablefor",
  "authors": "BeamNG",
  "roads": "levels.example.info.roads",
  "title": "levels.example.info.title",
  "description": "levels.example.info.description",
  "defaultSpawnPointName": "spawns_default",
  "country": "levels.common.country.usa",
  "region": "northAmerica",
  "biome": "levels.example.info.biome",
  "size": [2048, 2048],
  "localUnits": {
    "gasoline": "gallonUS",
    "diesel": "gallonUS"
  },
  "previews": [
    "preview.jpg",
    "preview_1.jpg"
  ],
  "spawnPoints": [
    {
      "translationId": "levels.example.spawnpoints.default",
      "description": "levels.example.spawnpoints.default.description",
      "logbookEntry": "levels.example.spawnpoints.default.logbookEntry",
      "objectname": "spawns_default",
      "preview": "spawns_default.jpg"
    }
  ],
  "roadRules": {
    "rightHandDrive": false,
    "turnOnRed": true
  },
  "supportsTraffic": true,
  "supportsTimeOfDay": true,
  "minimap": [
    {
      "file": "minimap/terrain.png",
      "size": [2048, 2048],
      "offset": [-1024, 1024]
    }
  ]
}

Loading behavior

When the level list is built, the level manager:

1. Scans /levels/.
2. Finds valid level directories.
3. Resolves the level entry point.
4. Reads info.json.
5. Adds mod/official metadata.
6. Adds runtime path fields.
7. Prefixes preview paths with the level directory.
8. Processes spawn point previews.
9. Marks the default spawn point if found.
10. Adds a fallback default spawn point if needed.
11. Prefixes minimap file paths.
12. Applies default values for missing support flags.

Best practices

• Always include info.json in the level root.
• Use translation IDs for UI-facing text.
• Provide at least one preview image.
• Make sure preview paths are relative to the level folder.
• Make sure defaultSpawnPointName matches a valid spawn point object.
• Keep spawn point objectname values stable once used by gameplay/career data.
• Use roadRules to match the real-world traffic side of the region.
• Use localUnits for regional unit display behavior.
• Avoid deprecated hidden; use isAuxiliary.
• Validate JSON syntax before shipping.
• Do not use trailing commas.
• Provide minimap data if the level supports map/big-map display.
• Set supportsTraffic or supportsTimeOfDay to false only when those systems are not supported.

Common issues

Level appears with folder name instead of title

Possible causes:

• Missing title
• Invalid translation ID
• Missing or invalid info.json

Preview image missing

Possible causes:

• Wrong path
• Image not included
• previews is empty
• Invalid filename or extension

Spawn point does not work

Possible causes:

• objectname does not match a scene object
• Spawn object is missing from items.level.json
• defaultSpawnPointName does not match any spawn point
• Spawn point object exists but is not loaded

Big map spawn POI missing

Possible causes:

• Spawn point has no objectname
• Referenced object cannot be found
• Spawn point is not discovered in career mode, where applicable

Minimap tile missing

Possible causes:

• Wrong file path
• Missing image file
• Invalid minimap entry
• Invalid JSON due to trailing comma

Time-of-day options missing

Possible causes:

• supportsTimeOfDay is false
• excludeDefaultTimeOfDayOptions is true and no custom presets are provided

Lane behavior feels wrong

Check:

"roadRules": {
  "rightHandDrive": false
}

Use the correct value for the traffic side represented by the level.

Fuel price display uses wrong units

Check:

"localUnits": {
  "gasoline": "gallonUS",
  "diesel": "gallonUS"
}

Only set local unit overrides when the level region requires them.

Summary

info.json is the primary metadata file for a level.

It defines:

• UI title and description
• Author and regional metadata
• Preview images
• Spawn point metadata
• Default spawn point
• Minimap tiles
• Road rules
• Local unit preferences
• Traffic support
• Time-of-day support and presets

A complete and valid info.json is essential for proper level discovery, UI display, spawning, minimap support, and gameplay integration.