Datablocks (.datablocks.json)

This document describes BeamNG datablock JSON files.

Datablocks are reusable engine data definitions. They are used by many systems to describe shared resources such as particles, emitters, precipitation, light flares, light animations, sounds, ambience, decals, and other reusable engine objects.

A datablock is not usually a visible level object by itself. Instead, it is a named definition that other objects, systems, or gameplay code can reference.

Overview

A datablock JSON file is a JSON object where each top-level key defines one datablock.

Example:

{
  "exampleData": {
    "name": "exampleData",
    "class": "SomeDatablockClass"
  }
}

Each datablock entry usually contains:

The top-level key and the name field should normally match.

File naming

Modern datablock files usually use the suffix:

*.datablocks.json

Examples:

art/datablocks/lights.datablocks.json
art/datablocks/sounds.datablocks.json
art/datablocks/audioProfiles.datablocks.json
art/datablocks/managedDatablocks.datablocks.json

Some managed datablock files use tool-specific names:

art/shapes/particles/managedParticleData.json
art/shapes/particles/managedParticleEmitterData.json

Level-specific datablocks may also exist inside level folders:

levels/<levelName>/datablocks/custom.datablocks.json

Loading behavior

During level loading, core datablocks are loaded before level objects. This allows scene objects and systems to reference datablocks by name.

Typical core files include:

art/shapes/particles/managedParticleData.json
art/shapes/particles/managedParticleEmitterData.json
art/datablocks/audioProfiles.datablocks.json
art/datablocks/sounds.datablocks.json
art/datablocks/player.datablocks.json
art/datablocks/datablockExec.datablocks.json
art/datablocks/lights.datablocks.json
art/datablocks/managedDatablocks.datablocks.json

When loading a level, the engine also searches the level folder for files matching patterns such as:

*.datablocks.json
*Data.json

These are loaded before level scene objects are created.

Legacy .cs datablocks

Older content may define datablocks in TorqueScript .cs files.

Examples:

datablockExec.cs

The engine still supports some legacy .cs datablock loading paths, but new content should use JSON datablock files.

General structure

A datablock file contains named entries:

{
  "datablockName": {
    "name": "datablockName",
    "class": "SomeDatablockClass",
    "fieldA": 1,
    "fieldB": "value"
  }
}

Minimal example:

{
  "TurretFireSound": {
    "name": "TurretFireSound",
    "class": "SFXProfile",
    "description": "AudioMaster",
    "filename": "art/sound/turret_firing.wav",
    "preload": true
  }
}

Common datablock classes

Common datablock classes include:

Class-specific fields are documented separately.

References between datablocks

Datablocks often reference each other by name.

Example:

{
  "exampleEmitter": {
    "name": "exampleEmitter",
    "class": "ParticleEmitterData",
    "particles": "exampleParticle"
  }
}

Here, exampleEmitter references a ParticleData datablock named exampleParticle.

If the referenced datablock is missing, the effect may fail or use fallback behavior.

Texture and audio paths

Many datablocks reference texture or audio assets.

Examples:

"textureName": "art/shapes/particles/steam.png"
"flareTexture": "core/art/special/lensFlareSheet0.color.png"
"dropTexture": "art/shapes/particles/Particle_rain_drop.dds"
"filename": "art/sound/turret_firing.wav"
"fileName": "event:>UI>Missions>Countdown_Go"

Use valid paths and make sure referenced files are included in the mod or level.

Persistent IDs

Some saved datablocks contain:

"persistentId": "c98465df-dd27-48d0-b855-3f5267b18400"

Persistent IDs are editor/engine identifiers used for object persistence.

When manually creating datablocks, avoid copying the same persistentId to another unrelated datablock.

Null and placeholder values

Saved datablock files may contain null values or empty placeholder entries.

Example:

{
  "elementDist": null,
  "elementRect": null,
  "elementScale": null
}

or:

{}

These usually represent unused array slots or default values written by the editor. Tools can generally ignore unused placeholder entries unless the specific datablock class requires them.

Editor workflow

Datablocks can be created and managed by editor tools.

When a datablock is created:

1. The editor creates an object of the selected datablock class.
2. It optionally copies fields from another datablock.
3. It registers the object.
4. It adds it to the datablock set.
5. It marks it dirty in the persistence manager.
6. It saves it to a datablock JSON file.

The editor tracks dirty datablocks and can save only modified objects.

Default managed datablock file

If no custom filename is provided, editor-created datablocks may be saved to a managed file such as:

art/datablocks/managedDatablocks.json

or a class/tool-specific managed file.

For organized content, prefer saving related datablocks into clearly named files.

Example:

levels/example/datablocks/traffic_lights.datablocks.json
levels/example/datablocks/weather_effects.datablocks.json
levels/example/datablocks/custom_sounds.datablocks.json

Minimal file example

{
  "exampleSound": {
    "name": "exampleSound",
    "class": "SFXProfile",
    "description": "AudioDefault3D",
    "fileName": "art/sound/example.ogg"
  },

  "exampleFlare": {
    "name": "exampleFlare",
    "class": "LightFlareData",
    "flareTexture": "core/art/special/lensFlareSheet0.color.png",
    "overallScale": 1
  }
}

Best practices

• Use JSON datablock files for new content.
• Keep datablock names unique.
• Keep the top-level key and name field consistent.
• Use descriptive names that include purpose or system.
• Load/create referenced datablocks before users of those datablocks.
• Avoid copying persistentId values between unrelated datablocks.
• Use asset paths that work both in normal game and packed mods.
• Prefer shared/common datablocks when possible.
• Use editor tools to create and save datablocks when available.
• Remove unused datablocks to reduce clutter and load time.
• Group related datablocks into clearly named files.

Common issues

Datablock is not found

Possible causes:

• File was not loaded.
• Wrong file suffix.
• Wrong name.
• Typo in referenced datablock name.
• Referenced before being loaded.

Referenced asset is missing

Possible causes:

• Texture/audio path is wrong.
• File is not included in the mod or level.
• Path works locally but not from a packed mod.
• Incorrect capitalization on case-sensitive systems.

Datablock loads but does nothing

Possible causes:

• No object or system references it.
• Required class-specific fields are missing.
• Referenced child datablock is missing.
• Datablock was saved to the wrong file.

Duplicate datablock names

Only one object should use a given datablock name. Rename one of them and update references.

Persistent ID conflict

Remove duplicated persistentId fields and let the editor regenerate them.

Summary

Datablock JSON files store reusable engine data definitions.

They can define particles, emitters, precipitation, light flares, light animations, sounds, ambience, decals, and other shared resources.

Modern datablocks should be stored in JSON files such as:

*.datablocks.json

or tool-specific managed JSON files.

Level objects and gameplay systems reference datablocks by name.