Forest Data (.forest4.json) and managedItemData.json

This document describes the modern BeamNG forest placement format used by levels:

• forest/*.forest4.json - forest item placement files
• art/forest/managedItemData.json - forest item type definitions

These files work together. managedItemData.json defines what can be placed, while .forest4.json files define where each item is placed in the level.

Overview

The Forest system is used for large numbers of repeated static objects, such as:

• Trees
• Bushes
• Grass clumps
• Rocks
• Logs
• Small vegetation props

Forest items are optimized for rendering and collision. They are generally not meant to be individually moved or animated during gameplay, but they can support wind animation through their asset setup and forest item parameters.

A typical level uses:

levels/example_level/
├── art/
│   └── forest/
│       └── managedItemData.json
└── forest/
    ├── trees.forest4.json
    ├── rocks.forest4.json
    └── bushes.forest4.json

File roles

managedItemData.json

managedItemData.json defines reusable forest item types. Each item type references a shape file and optional physical/wind parameters.

Location

levels/<levelName>/art/forest/managedItemData.json

Basic structure

The file is a JSON object. Each top-level entry contains a forest item data block.

{
  "oak_large": {
    "class": "ForestItemData",
    "internalName": "oak_large",
    "shapeFile": "/levels/example/art/shapes/trees/oak_large.dae",
    "mass": 100,
    "rigidity": 10,
    "tightnessCoefficient": 0.5,
    "dampingCoefficient": 0.2,
    "windScale": 1,
    "trunkBendScale": 0.5,
    "branchAmp": 1,
    "detailAmp": 0.25,
    "detailFreq": 1
  }
}

The supported class names are:

ForestItemData
TSForestItemData

Both are accepted by the loader.

managedItemData.json fields

Not all fields are required, but internalName and shapeFile are essential.

Forest item names

The internalName is the link between item definitions and placed instances.

Example item definition:

"pine_small": {
  "class": "ForestItemData",
  "internalName": "pine_small",
  "shapeFile": "/levels/example/art/shapes/trees/pine_small.dae"
}

Example placement referencing it:

{"type":"pine_small","pos":[10,20,0],"rotationMatrix":[1,0,0,0,1,0,0,0,1],"scale":1}

If a placement references a type that does not exist in managedItemData.json, that instance cannot be resolved.

.forest4.json placement files

.forest4.json files store placed forest item instances.

Location

levels/<levelName>/forest/*.forest4.json

Example:

levels/example/forest/trees.forest4.json

File format

.forest4.json files are line-delimited JSON.

This means each line is a separate JSON object. The file is not a single JSON array.

Example:

{"type":"pine_small","pos":[10,20,0],"rotationMatrix":[1,0,0,0,1,0,0,0,1],"scale":1}
{"type":"pine_small","pos":[15,25,0],"rotationMatrix":[0,-1,0,1,0,0,0,0,1],"scale":0.85}
{"type":"rock_large","pos":[30,12,0],"rotationMatrix":[1,0,0,0,1,0,0,0,1],"scale":1.4}

.forest4.json fields

Example instance

{
  "type": "oak_large",
  "pos": [100.5, 42.0, 12.3],
  "rotationMatrix": [
    1, 0, 0,
    0, 1, 0,
    0, 0, 1
  ],
  "scale": 1.0
}

Loading process

When a level is loaded, the engine roughly follows this process:

1. Look for forest item data:

   • art/forest/managedItemData.json
   • fallback to art/forest/managedItemData.cs

2. Parse all valid forest item definitions.

3. Search the level forest folder for:

forest/*.forest4.json

4. Read each .forest4.json file line by line.

5. For each placement:

   • Read type
   • Find matching internalName in item data
   • Resolve shapeFile
   • Read position, rotation, and scale
   • Add the instance to the forest system

Legacy forest formats

The engine can still detect older forest files:

*.forest
*.forest.json

These are deprecated. If old files are present, the engine may print warnings similar to:

Old forest file format detected. Please resave the forest and delete the old files.

Modern levels should use:

*.forest4.json

Legacy managedItemData.cs

If managedItemData.json is missing, the engine can fall back to:

art/forest/managedItemData.cs

This is the older TorqueScript-style format.

Example:

datablock ForestItemData(oak_large)
{
   internalName = "oak_large";
   shapeFile = "/levels/example/art/shapes/trees/oak_large.dae";
   mass = "100";
   rigidity = "10";
   windScale = "1";
};

For new content, prefer managedItemData.json.

Wind parameters

Forest items can react to wind if the asset and material support it. The item data values control how strongly the object responds.

Common wind-related fields:

Example for a tree:

{
  "class": "ForestItemData",
  "internalName": "pine_large",
  "shapeFile": "/levels/example/art/shapes/trees/pine_large.dae",
  "windScale": 1,
  "trunkBendScale": 0.6,
  "branchAmp": 1,
  "detailAmp": 0.25,
  "detailFreq": 1.5
}

Example for a rock:

{
  "class": "ForestItemData",
  "internalName": "rock_large",
  "shapeFile": "/levels/example/art/shapes/rocks/rock_large.dae",
  "windScale": 0
}

Collision and physics

Forest items can contribute collision depending on their shape and item setup. The engine builds collision data per forest cell and can reuse collision data for repeated shapes.

This is important for performance: many instances using the same shapeFile can share cached collision information.

For best results:

• Use simple collision meshes where possible.
• Avoid overly complex collision on dense vegetation.
• Disable collision for small decorative foliage when not needed.
• Use correct material ground types for collision surfaces.

Performance notes

The forest system is designed for large numbers of repeated static objects, but performance still depends on asset quality.

Important factors:

• Number of unique shapeFile assets
• Triangle count
• Material count
• Collision complexity
• Density of placements
• Wind animation usage
• Draw distance and LODs
• Imposter support

Use the Forest Editor and debug tools to validate placement density and performance.

Best practices

• Use managedItemData.json for new levels.
• Use .forest4.json placement files.
• Keep each .forest4.json as line-delimited JSON.
• Make sure every placement type matches an internalName.
• Reuse item types instead of duplicating similar definitions.
• Use LODs and imposters for trees and large vegetation.
• Keep collision simple.
• Set windScale to 0 for objects that should not move.
• Remove old .forest and .forest.json files after upgrading.
• Keep shape paths valid and consistent.

Common issues

Forest items do not appear

Possible causes:

• Missing managedItemData.json
• Placement type does not match any internalName
• Invalid shapeFile path
• Invalid JSON line in .forest4.json
• File is saved as a JSON array instead of line-delimited JSON

Some forest items are missing

Check console/log output for invalid lines or missing item types. A single bad line may fail while other lines still load.

Forest item has wrong rotation

Check that rotationMatrix contains 9 valid numeric values.

Forest item has wrong size

Check the scale field. .forest4.json uses a single uniform scale value.

Wind does not affect item

Possible causes:

• windScale is 0
• Asset does not support wind deformation
• Vertex color setup does not drive wind correctly
• Material/shader does not support wind features

Old forest files still load

If the level contains both old and new forest files, remove deprecated files after verifying the upgraded .forest4.json data.

Minimal example

art/forest/managedItemData.json

{
  "pine_small": {
    "class": "ForestItemData",
    "internalName": "pine_small",
    "shapeFile": "/levels/example/art/shapes/trees/pine_small.dae",
    "windScale": 1,
    "trunkBendScale": 0.4,
    "branchAmp": 1,
    "detailAmp": 0.25,
    "detailFreq": 1
  },
  "rock_large": {
    "class": "ForestItemData",
    "internalName": "rock_large",
    "shapeFile": "/levels/example/art/shapes/rocks/rock_large.dae",
    "windScale": 0
  }
}

forest/forest.forest4.json

{"type":"pine_small","pos":[0,0,0],"rotationMatrix":[1,0,0,0,1,0,0,0,1],"scale":1}
{"type":"pine_small","pos":[5,2,0],"rotationMatrix":[0,-1,0,1,0,0,0,0,1],"scale":0.9}
{"type":"rock_large","pos":[10,4,0],"rotationMatrix":[1,0,0,0,1,0,0,0,1],"scale":1.5}

Summary

The modern forest format uses two parts:

• managedItemData.json defines reusable forest item types.
• .forest4.json files store placed instances as line-delimited JSON.

This structure allows the engine to efficiently render, batch, collide, and manage large numbers of repeated static objects in a level.