Forest Brushes (.forestbrushes4.json)

This document describes Forest Brush data used by the World Editor Forest Editor.

Forest Brushes are editor-only groups of placement rules used to paint forest items into a level. A brush can contain one or more ForestBrushElement objects. Each element references a ForestItemData type and defines how that item should be randomly placed.

Forest Brushes do not directly store placed forest instances. They are tools for creating forest placement data.

Overview

A Forest Brush is a container of one or more brush elements.

Each ForestBrushElement controls:

• Which forest item type can be placed
• How likely it is to be selected
• Random rotation range
• Random scale range
• Slope limits
• Elevation limits
• Sink/depth adjustment

This allows a single brush stroke to paint a natural-looking mixture of trees, rocks, bushes, grass clumps, and other forest items.

Example use cases:

• Mixed tree brushes
• Rock scatter brushes
• Bush/grass undergrowth brushes
• Elevation-specific vegetation
• Slope-restricted cliff rocks
• Randomized forest density and scale variation

Object types

ForestBrush

ForestBrush is a container class for ForestBrushElement objects.

It is used by the editor only and is stored under a special group:

ForestBrushGroup

If ForestBrushGroup does not exist, the engine creates it automatically.

A ForestBrush only accepts ForestBrushElement children. Other object types are ignored when added to the brush.

ForestBrushElement

A ForestBrushElement represents one possible forest item type in a brush.

For example, a “mixed pine forest” brush may contain:

• Small pine element
• Medium pine element
• Large pine element
• Bush element
• Rock element

Each element has its own probability, scale, slope, and elevation settings.

Fields

Probability

probability controls how often an element is selected relative to other elements in the same brush.

It is not an absolute percentage by itself. Instead, the chance is based on the element’s probability divided by the sum of all probabilities in the brush.

Example:

Total probability:

3 + 2 + 1 = 6

So:

Pine small = 3 / 6 = 50%
Pine large = 2 / 6 = 33%
Rock       = 1 / 6 = 17%

Use higher probability for common items and lower probability for rare accent items.

Rotation range

rotationRange controls random yaw rotation.

Example:

"rotationRange": 360

This allows full random rotation and is useful for trees, rocks, bushes, and most natural objects.

Smaller values restrict rotation variation:

"rotationRange": 30

This can be useful for objects that need a more consistent orientation.

Scale range

scaleMin and scaleMax define random item scale.

Example:

"scaleMin": 0.8,
"scaleMax": 1.3

This creates variation so repeated assets do not look identical.

Typical usage:

Scale exponent

scaleExponent biases the random scale distribution between scaleMin and scaleMax.

Default:

"scaleExponent": 1

A value of 1 gives a normal linear distribution.

Higher or lower values can bias the result toward smaller or larger instances, depending on the random distribution used by the editor.

Use this when you want most items to be near one end of the scale range instead of evenly distributed.

Sink settings

Sink settings help place items naturally into terrain.

These are useful for:

• Trees on slopes
• Rocks partially embedded in terrain
• Bushes that should not appear floating
• Large objects with uneven bases

Example:

"sinkMin": 0.05,
"sinkMax": 0.2,
"sinkRadius": 1.5

This allows the object to be placed slightly below the terrain surface to avoid visible gaps.

Slope limits

slopeMin and slopeMax restrict placement based on surface slope.

Example for normal trees:

"slopeMin": 0,
"slopeMax": 35

Example for cliff rocks:

"slopeMin": 25,
"slopeMax": 80

This helps control where items appear:

• Trees on flatter terrain
• Rocks on steep slopes
• Grass on gentle hills
• No large vegetation on cliffs

Elevation limits

elevationMin and elevationMax restrict placement based on world-space height.

Example:

"elevationMin": 200,
"elevationMax": 800

This is useful for biome control:

• Lowland vegetation
• Mountain trees
• Alpine rocks
• Beach plants
• Snow-line vegetation

Example brush setup

A mixed forest brush could contain three elements:

{
  "class": "ForestBrush",
  "name": "mixed_pine_forest"
}

Example elements:

{
  "class": "ForestBrushElement",
  "forestItemData": "pine_small",
  "probability": 4,
  "rotationRange": 360,
  "scaleMin": 0.8,
  "scaleMax": 1.2,
  "slopeMin": 0,
  "slopeMax": 35,
  "elevationMin": -10000,
  "elevationMax": 10000
}

{
  "class": "ForestBrushElement",
  "forestItemData": "pine_large",
  "probability": 2,
  "rotationRange": 360,
  "scaleMin": 0.9,
  "scaleMax": 1.4,
  "slopeMin": 0,
  "slopeMax": 30
}

{
  "class": "ForestBrushElement",
  "forestItemData": "rock_medium",
  "probability": 1,
  "rotationRange": 360,
  "scaleMin": 0.6,
  "scaleMax": 1.8,
  "sinkMin": 0.05,
  "sinkMax": 0.2,
  "sinkRadius": 1.2,
  "slopeMin": 10,
  "slopeMax": 75
}

In this brush:

• Small pines are common
• Large pines are less common
• Rocks appear occasionally
• Trees avoid steep slopes
• Rocks can appear on steeper terrain

Relationship with ForestItemData

forestItemData must reference a valid forest item definition.

Forest item data is usually defined in:

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

Example item data:

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

Brush element reference:

"forestItemData": "pine_small"

If the referenced item data does not exist, the brush element cannot place that object.

Best practices

• Use multiple brush elements for natural variation.
• Use probability to control common vs rare items.
• Use scale ranges to avoid repetition.
• Use slope limits to prevent trees from appearing on cliffs.
• Use elevation limits for biome control.
• Use small sink values for rocks and trees on slopes.
• Set windScale in ForestItemData, not the brush, for wind behavior.
• Keep brush elements focused; create separate brushes for different biomes or asset groups.

Common issues

Brush does not place an item

Possible causes:

• forestItemData is missing or invalid
• Referenced ForestItemData does not exist
• Slope is outside slopeMin / slopeMax
• Elevation is outside elevationMin / elevationMax
• Probability is too low compared to other elements

Items float above terrain

Increase sink values slightly or check asset origin/pivot.

Items are buried too deeply

Reduce sinkMin, sinkMax, or sinkRadius.

Too many repeated-looking items

Increase rotation variation, widen scale range, or add more brush elements.

Items appear on cliffs

Lower slopeMax.

Rocks do not appear on slopes

Increase slopeMax or raise slopeMin depending on the desired placement range.

Summary

Forest Brushes are editor-only placement tools used by the Forest Editor.

A brush contains one or more ForestBrushElement objects. Each element references a ForestItemData type and defines how that item should be randomly placed using probability, rotation, scale, sinking, slope, and elevation rules.

They are used to efficiently paint natural-looking forests, rocks, bushes, and other repeated level vegetation.