Ground Models (groundmodels.json)

This document describes groundmodels.json, the file format used to define physical surface behavior in BeamNG.

Ground models describe how tires, wheels, props, and other physics objects interact with surfaces such as asphalt, gravel, sand, mud, snow, grass, or water-like materials.

They affect:

• Tire grip
• Sliding friction
• Rolling resistance / roughness
• Deformation and sinking
• Hydrodynamic/fluid resistance
• Particle/collision material type
• Skid mark behavior

File locations

The common/global ground model file is:

/art/groundmodels.json

Levels can add or override ground models with JSON files inside:

levels/<levelName>/groundModels/*.json

During level load, the engine:

1. Loads the common file:

/art/groundmodels.json

2. Searches the current level folder for:

groundModels/*.json

3. Merges level ground models into the common set.
4. Submits all ground models to the physics engine.

Level files can override common ground models by using the same name.

Basic structure

A ground model file is a JSON object where each key is the ground model name.

Example:

{
  "asphalt_special": {
    "roughnessCoefficient": 0,
    "staticFrictionCoefficient": 1.0,
    "slidingFrictionCoefficient": 0.9,
    "hydrodynamicFriction": 0.01,
    "stribeckVelocity": 6,
    "strength": 1,
    "collisiontype": "ASPHALT",
    "fluidDensity": 200,
    "flowConsistencyIndex": 10000,
    "flowBehaviorIndex": 0.5,
    "dragAnisotropy": 0,
    "skidMarks": true,
    "defaultDepth": 0,
    "shearStrength": 0
  }
}

Ground model names

Ground model names are converted to uppercase when loaded.

Example:

"asphalt_special": {}

becomes:

ASPHALT_SPECIAL

Names longer than 31 characters are truncated.

Aliases

A ground model can define aliases:

{
  "asphalt_special": {
    "aliases": ["road_special", "tarmac_extra"],
    "staticFrictionCoefficient": 1.0,
    "slidingFrictionCoefficient": 0.9
  }
}

This registers multiple names for the same ground model data:

ASPHALT_SPECIAL
ROAD_SPECIAL
TARMAC_EXTRA

Aliases are useful when different systems, terrain materials, or older content use different names for the same surface behavior.

Fields

Deprecated / typo fields

The loader detects some old misspelled fields and logs errors.

Use:

"hydrodynamicFriction"

not:

"hydrodnamicFriction"

Use:

"flowBehaviorIndex"

not:

"flowBehaviourIndex"

The old names may still be read for compatibility, but they should be fixed.

Unknown fields

Unknown attributes are ignored and logged as errors.

Example:

Unknown ground model attribute: myCustomValue - IGNORED

Only supported fields should be used.

Friction fields

staticFrictionCoefficient

Controls grip when the tire/contact patch is not sliding.

Higher values generally mean more grip.

Example:

"staticFrictionCoefficient": 1.0

slidingFrictionCoefficient

Controls grip while sliding.

Example:

"slidingFrictionCoefficient": 0.8

Usually this is lower than static friction.

Roughness

roughnessCoefficient controls physical roughness of the surface.

Example:

"roughnessCoefficient": 0.05

Rougher surfaces can make driving feel bumpier or less smooth, depending on vehicle and tire interaction.

Depth and soft ground

defaultDepth is used for ground models that represent soft or deformable surfaces.

Example:

"defaultDepth": 0.15

This is useful for:

• Mud
• Sand
• Snow
• Gravel
• Deep dirt

Fluid/deformable parameters

These fields control more advanced fluid-like or deformable ground behavior:

"fluidDensity": 800,
"flowConsistencyIndex": 12000,
"flowBehaviorIndex": 0.6,
"hydrodynamicFriction": 0.05

They are useful for surfaces such as:

• Mud
• Wet sand
• Deep snow
• Water-like resistance zones

Collision type

collisiontype links the ground model to a particle/collision material name.

Example:

"collisiontype": "DIRT"

The value is resolved through the particle materials table.

This can affect effects such as:

• Particles
• Dust
• Debris
• Surface interaction visuals

Skid marks

skidMarks controls whether skid marks are allowed on this ground model.

Example:

"skidMarks": true

Typical usage:

Level-specific ground models

Levels can override or add ground models by placing JSON files in:

levels/<levelName>/groundModels/

Example:

levels/example/groundModels/wet_surfaces.json

{
  "wet_asphalt": {
    "aliases": ["rain_asphalt"],
    "staticFrictionCoefficient": 0.75,
    "slidingFrictionCoefficient": 0.55,
    "roughnessCoefficient": 0.01,
    "hydrodynamicFriction": 0.03,
    "collisiontype": "ASPHALT",
    "skidMarks": true
  }
}

Level files are merged after the common file, so they can replace common definitions if they use the same name.

Relationship with terrain materials

Terrain materials can reference a ground model using:

groundmodelName

Example terrain material field:

"groundmodelName": "grass"

When a vehicle drives over terrain using that material, the corresponding ground model controls the physical surface behavior.

Relationship with object materials

Materials can also define ground/collision behavior through their physical material settings, depending on object type and collision setup.

For terrain specifically, TerrainMaterial.groundmodelName is the important link.

Reloading

Ground models are loaded during mission start.

They can also reload when one of the loaded ground model JSON files changes. When that happens, the environment system reloads ground models and collision may be reloaded so the new values take effect.

Minimal example

{
  "asphalt_special": {
    "aliases": ["road_special", "tarmac_extra"],
    "roughnessCoefficient": 0,
    "staticFrictionCoefficient": 1.0,
    "slidingFrictionCoefficient": 0.9,
    "hydrodynamicFriction": 0.01,
    "stribeckVelocity": 6,
    "strength": 1,
    "collisiontype": "ASPHALT",
    "fluidDensity": 200,
    "flowConsistencyIndex": 10000,
    "flowBehaviorIndex": 0.5,
    "dragAnisotropy": 0,
    "skidMarks": true,
    "defaultDepth": 0,
    "shearStrength": 0
  },

  "mud_deeper": {
    "aliases": ["deep_mud"],
    "roughnessCoefficient": 0.15,
    "defaultDepth": 0.25,
    "staticFrictionCoefficient": 0.55,
    "slidingFrictionCoefficient": 0.35,
    "hydrodynamicFriction": 0.08,
    "stribeckVelocity": 4,
    "strength": 0.4,
    "collisiontype": "MUD",
    "fluidDensity": 900,
    "flowConsistencyIndex": 15000,
    "flowBehaviorIndex": 0.6,
    "dragAnisotropy": 0,
    "skidMarks": false,
    "shearStrength": 0.2
  }
}

Best practices

• Keep names short and descriptive.
• Use aliases for backwards compatibility or alternate names.
• Use level-specific files only for level-specific behavior.
• Keep static friction higher than sliding friction in most cases.
• Use skidMarks only where marks make sense.
• Use defaultDepth and fluid/deformable parameters for soft terrain.
• Avoid unknown fields; they are ignored.
• Fix typo/deprecated fields when found in logs.
• Test vehicle behavior after changing friction or depth values.

Common issues

Ground model does not apply

Possible causes:

• Terrain material has wrong groundmodelName
• Ground model name was truncated
• Ground model file did not load
• Name mismatch after uppercase conversion
• Material/collision setup does not use that ground model

Warning about unknown attribute

The JSON contains an unsupported field. Remove or rename it.

Warning about misspelled field

Replace old typo fields:

hydrodnamicFriction → hydrodynamicFriction
flowBehaviourIndex → flowBehaviorIndex

Surface has too much grip

Lower:

"staticFrictionCoefficient"
"slidingFrictionCoefficient"

Surface feels too soft or deep

Reduce:

"defaultDepth"
"hydrodynamicFriction"
"fluidDensity"
"flowConsistencyIndex"

Skid marks missing

Check:

"skidMarks": true

and verify that the material/ground interaction supports skid marks.

Summary

groundmodels.json defines physical surface behavior.

It controls how vehicles and physics objects interact with surfaces through friction, roughness, depth, drag, particle collision type, and skid mark settings.

The common file is loaded first:

/art/groundmodels.json

Level-specific overrides are loaded from:

levels/<levelName>/groundModels/*.json

Ground models are linked to terrain through TerrainMaterial.groundmodelName.