Materials (*.materials.json)

BeamNG material JSON files define Material objects for levels, vehicles, shared art, decals, roads, water, skyboxes, props, and other rendered content.

For material authoring concepts, see the Materials section. For the World Editor window, see Material Editor .

File names

Common material files include:

main.materials.json
skin.materials.json
*.materials.json

Examples:

levels/<levelName>/main.materials.json
levels/<levelName>/art/shapes/buildings/main.materials.json
vehicles/<vehicleName>/main.materials.json
vehicles/<vehicleName>/skin.materials.json
art/shapes/objects/main.materials.json

Material JSON files are loaded from game, level, vehicle, and mod paths, depending on the content being loaded.

Basic structure

A material file is a JSON object. Each top-level key defines one material.

{
  "m_concrete_wall": {
    "name": "m_concrete_wall",
    "class": "Material",
    "mapTo": "m_concrete_wall",
    "baseColorMap": ["/levels/example/art/textures/concrete_b.color.png"],
    "normalMap": ["/levels/example/art/textures/concrete_n.normal.png"],
    "roughnessMap": ["/levels/example/art/textures/concrete_r.roughness.png"],
    "metallicFactor": [0],
    "roughnessFactor": [1]
  }
}

The top-level key and name usually match.

Important fields

Field	Type	Description
`class`	string	Usually `"Material"`.
`name`	string	Material object name. Usually matches the top-level key.
`mapTo`	string	Mesh/material slot name this material maps to.
`baseColorMap`	array[path]	Base color texture path per material layer.
`normalMap`	array[path]	Normal map texture path per material layer.
`roughnessMap`	array[path]	Roughness map texture path per material layer.
`metallicMap`	array[path]	Metallic map texture path per material layer.
`baseColorFactor`	array/color	Base color multiplier where present.
`roughnessFactor`	array[number]	Roughness scalar per layer.
`metallicFactor`	array[number]	Metallic scalar per layer.
`emissiveMap`	array[path]	Emissive texture path where used.
`emissiveIntensityNits`	array[number]	Physical emissive brightness per layer, in nits.
`retroreflectivity`	array[number]	Retroreflective strength per layer. `0` is off, `1` is full strength.
`retroreflectiveColor`	array[color]	Optional retroreflective color filter per layer. `[0, 0, 0]` or an omitted value applies the effect to all base colors.
`alphaRef`	number	Alpha cutoff value where used.
`translucent`	bool	Enables translucent rendering where used.
`useAnisotropic`	bool	Enables anisotropic filtering where used.
`annotation`	string	Optional annotation/debug classification.

Material definitions can contain renderer-specific fields. Preserve unknown fields when writing tools.

Do not delete fields only because they are not listed here. Material JSON often contains renderer, editor, compatibility, or generated fields.

mapTo

mapTo links a material definition to a material slot name used by a mesh or generated geometry.

Example:

"mapTo": "road_asphalt"

For imported meshes, mapTo should match the material name assigned in the DAE/DTS source file.

For objects that reference materials directly, such as DecalRoad.material or MeshRoad.topMaterial, the object field usually references the material object name.

Texture arrays

Many texture fields are saved as arrays because materials can support multiple layers.

Example:

"baseColorMap": [
  "/levels/example/art/textures/concrete_b.color.png"
]

A one-layer material still commonly uses an array with one entry.

Retro reflectivity

retroreflectivity is a version: 1.5 per-layer property for materials that should return local lights toward the light source, such as road signs, license plates, reflective stickers, and reflector lenses.

"Stages": [
  {
    "baseColorMap": "/vehicles/example/example_sign_b.color.png",
    "retroreflectivity": 1,
    "retroreflectiveColor": [1, 1, 1]
  },
  {},
  {},
  {}
],
"version": 1.5

Use retroreflectivity values between 0 and 1. Use retroreflectiveColor only when the effect should be limited to matching base-color areas. For example, [1, 1, 1] favors white sign sheeting, [1, 1, 0] favors yellow markers, and [0, 0, 0] or an omitted value applies retro reflectivity to every color.

Retro reflectivity is separate from cubemap or environment reflections. reflectivityMap and reflectivityMapFactor are legacy material fields and should not be used for new version: 1.5 materials.

Material paths

Use paths that work from normal game content and packed mods.

Common paths:

/levels/<levelName>/art/textures/...
/levels/<levelName>/art/shapes/...
/vehicles/<vehicleName>/...
/art/shapes/objects/...

Keep capitalization consistent.

Relationship with terrain materials

Normal Material definitions are separate from TerrainMaterial definitions.

Type	Main use
`Material`	Meshes, decals, water, skyboxes, roads, props, vehicles, and general rendering.
`TerrainMaterial`	Terrain painting, terrain texture layers, and terrain groundmodel links.

For terrain-specific material data, see Terrain files .

Tool notes

When generating or editing material files:

Preserve unknown fields.
Preserve top-level material keys and name values unless intentionally renaming.
Update mapTo only when mesh material slot names change.
Keep texture fields as arrays when the source file uses arrays.
Validate referenced texture paths.
Keep normal maps in the expected orientation for BeamNG rendering.
Avoid generating duplicate material names across loaded material files.

Common issues

Mesh shows a warning material because mapTo does not match the mesh material slot.
Material is not found because the material file was saved outside a loaded path.
Texture is missing because the path is wrong or not included in the mod.
Material looks too shiny because roughness values or roughness maps are wrong.
Imported mesh uses a different material name than the BeamNG material definition.

Validation criteria

Material JSON loads without parse errors.
Material names are unique in the loaded content scope.
mapTo values match mesh source material slots where needed.
Texture paths exist and use expected formats.
Referencing objects such as TSStatic, DecalRoad, MeshRoad, WaterObject, SkyBox, or vehicle parts render without warning materials.

Materials (*.materials.json)

File names

Basic structure

Important fields

mapTo

Texture arrays

Retro reflectivity

Material paths

Relationship with terrain materials

Tool notes

Common issues

Validation criteria

On this page:

Any further questions?