# Foliage and biomes

> Scatter models and generated trees over the terrain, tune grass and wind, and split the world into biomes that dress the ground.

Source: https://feather-engine.com/docs/world/foliage-and-biomes/

Vegetation in Feather Engine 2 comes from three sources. **Foliage layers** scatter imported models
and generated trees over the terrain. **Tree designs** are small recipes the engine turns into
stylized trees. The **built-in grass** grows around the camera on open ground. **Biomes** then vary
all three across the world, together with the terrain height and ground colour.

Everything is deterministic: the same settings place the same plants in the editor, in Play and in
an exported game.

## Scatter models with foliage layers

1. Import the models you want to scatter, such as bushes, rocks or tree models. See
   [Assets](/docs/concepts/assets/).
2. Open **Window → World & terrain → Foliage**.
3. Click **+ Add foliage layer** and tick the models it scatters. The button is available once the
   project has imported models.
4. Set the density, scale and slope range.

| Setting | Field | Range | Description |
| --- | --- | --- | --- |
| Per 100 m² | `density` | 0–400 | Instances per 100 m² |
| Min scale / Max scale | `scale` | 0.05–5 in the panel, 0.01–50 by command | Random scale range |
| Min slope / Max slope | `min_slope`, `max_slope` | 0 (flat) – 1 (vertical) | Where the layer may grow |
| View distance (chunks) | `view_chunks` | 1–8 | Spawn ring in 32 m chunks; default 4 |
| Trunk collider m | `collider_radius` | 0–3 in the panel, 0–20 by command | 0 means no collider |
| Keep off roads and paint | `avoid_paint` | On/off | |
| Keep out of flattened areas | `avoid_flattened` | On/off | |
| Cast shadows | `cast_shadows` | On/off | |
| Wind sway | `wind` | 0–3, or automatic | Automatic is 0 for models named as rocks or stones, otherwise 1 |
| Groves | `clustering` | 0–1; default 0 | 0 scatters evenly. Towards 1, instances gather in groves with open glades between, at about the same overall count |
| Grove size m | `cluster_size` | 4–500 m; default 28 | Shown when **Groves** is above 0 |
| Placement | `placement` | Everywhere / Painted, by command only | **Painted** layers grow only where you paint them in. The panel has no control for it; set it with `tree.forest` or `landscape.layout` |

To paint a layer in or out by hand, use **Paint foliage** and **Erase foliage** in the
[Landscape workspace](/docs/world/landscape/). **Remove foliage** erases every layer, including
grass, and **Restore foliage** brings it back.

## Design trees

Tree designs are recipes: trunk, branches, canopy style and colours. Each design produces four
differently shaped variants, so one design can fill a forest.

1. Open **Window → World & terrain → Trees**.
2. Next to **New tree**, click a preset: oak, birch, pine, palm, willow, cherry, autumn, dead, bush,
   maple, spruce, cypress, acacia, apple, ancient, sapling or berry bush.
3. Adjust the sections below. **Variant** previews each of the four variants, and **New shape**
   re-rolls the random seed.
4. Under **On the map**, set **Trees per 100 m²** and click **Scatter all designs** or **Only this
   one**. This creates or updates a foliage layer named Trees.

| Section | Settings |
| --- | --- |
| Trunk | Height (0.3–40 m), Thickness (0.03–3 m), Taper, Lean, Bend, Roots, Size variety (0–0.6), Gnarl, Forked trunk, Bark tint, Moss and Moss colour, and a bark: **Painted (built-in)** or a library bark |
| Branches | Branches (0–12), Angle (0–120°), Length, Start, Turn up, Side branches (0–4) |
| Canopy | Style (Puffy, Pine, Palm, Willow, Bare, Cone or Umbrella), Clumps (1–16), Clump size (0.2–8 m), Crown width (0.3–2.5), Flatten (0–0.9), Lumpiness, Leafy edge, leaf colours, Variation, Blossom, Fruit and Fruit colour |
| Wind and damage | Sway (0–3), Breakable, Health, Storm breaks it above (5–60 m/s) |

| Setting | Field | Range | Default | Description |
| --- | --- | --- | --- | --- |
| Size variety | `size_variety` | 0–0.6 | 0.12 | How different in height the four variants are |
| Gnarl | `gnarl` | 0 (straight) – 1 (old and twisted) | 0.25 | Crooked, knotted trunk and branches |
| Forked trunk | `trunk_fork` | 0–1 | 0 | Chance the trunk splits into two leaders |
| Moss | `moss`, `moss_color` | 0–1 | 0 | Moss on the upper side of the bark and the roots |
| Side branches | `twigs` | 0–4 | 2 | Branches forking off each branch. Every branch end holds a leaf clump, so more side branches make more, smaller clumps and a fuller crown |
| Crown width | `crown_width` | 0.3 (narrow) – 2.5 (very broad) | 1 | Branch reach, and the width of pine tiers and cones |
| Flatten | `crown_flatten` | 0 (round) – 0.9 (flat pads) | 0 | Squashes the leaf clumps |
| Fruit | `fruit`, `fruit_color` | 0–1 | 0 | Fruit or berries in the canopy |

**Cone** stacks clumps up the trunk into a narrow cone, as on a cypress or poplar. **Umbrella**
spreads a flat, wide crown on spreading branches, as on an acacia. Fruit trees blossom in spring
instead of fruiting.

Trees sway with the world wind, gusts and the weather. Bullets, melee swings, blasts, tornadoes
and wind above the limit damage them; they shake and shed leaves, and when broken they topple as
physics bodies and leave a stump. A storm limit of 60 m/s never breaks the tree.

The season changes broadleaf trees through the year; see
[Sky, weather and climate](/docs/world/sky-weather-climate/#seasons).

## Plant a forest kit

A forest kit plants a layered forest in one step: canopy trees in groves, a few giants and an
understory. In the **Trees** tab, click a kit next to **Forest kit**.

| Kit | Contents |
| --- | --- |
| Woodland | Groves of oaks, maples and birches with glades between, a few ancient giants, and bushes, berry bushes and saplings underneath |
| Conifer | Dark stands of spruces, pines and cypresses, with saplings between them |
| Autumn | Autumn trees among birches and maples, with bushes and berry bushes underneath |
| Savanna | Lone acacias far apart, with clumps of bushes |
| Orchard | Evenly spaced apple and cherry trees, with berry bushes |
| Ancient | An old, mossy forest: ancient giants, oaks, willows and maples, with thick undergrowth |
| Tropical | Palms and maples in loose clusters, with bushes and berry bushes |

A kit adds the tree designs it needs from the presets, with matching library barks when the texture
library is installed. Designs you already have with the same ID are kept and used as they are. It
replaces the foliage layers **Trees**, **Giants** and **Understory** (a layer's **Placement** is
kept), removes those a kit doesn't use, and turns off **Procedural trees, rocks and flowers**. Tune
the layers afterwards in the **Foliage** tab. Applying a kit is one undo step.

## Grass

The built-in grass grows in a field around the camera on open terrain. It stays off roads, painted
layers, rivers, flattened plots, water and the ground under buildings.

1. Open **Window → World & terrain → Ambience**.
2. Under **Grass**, pick a **Preset**: meadow (the default), lush, lawn, savanna, autumn, toon,
   alien, wildflowers, forest floor, highland or tundra.
3. Adjust **Grass**, **Grass colour** and **Grass motion**.

| Setting | Range | Description |
| --- | --- | --- |
| Amount | 0–2 | Density |
| Blade shape | Sharp / Soft / Wide | |
| Other shapes mixed in | 0–1 | Share of blades in another shape, such as broad weeds among sharp blades. Default 0.15 |
| Curvature | 0–1 | How far the blades arc over. Default 0.4 |
| Soft shading | 0–1 | Rounded shading across each blade, from flat cards to fully rounded. Default 0.6 |
| Field radius | 10–60 m | How far from the camera grass grows |
| Match the ground | On/off | Takes the colour from the base terrain layer |
| Root shade, Variation | 0–1 | |
| Sun-bleached tips, Tip colour (bleached) | 0–1; sRGB | How much the top of each blade takes the bleached colour. Default 0.22 |
| Patches, Patch size | 0–1; 2–200 m | Colour patches |
| Sun through blades | 0–2 | Translucency |
| Trees match the grass | 0–1 | Generated trees take on the grass colour where they grow |
| Flowers | 0–0.3 | Share of flowering blades |
| Flowers in patches | 0–1 | 0 scatters flowers evenly; 1 grows them only in patches of one colour. Default 0.6 |
| Flower size | 0.5–2.5 | Flower head size. Default 1 |
| Wind sway, Gusts | 0–3; 0–2 | |
| Gust size | 4–80 m | Size of the gust fronts rolling over the field. Default 18 m |
| Trampling, Player reach | 0–2; 0.2–5 m | The player, characters, rolling bodies and blasts press trails into the grass |
| Stands back up in | 0.2–60 s | |
| Springy (wobbles back) | 0–1 | Trampled grass overshoots and wobbles as it stands up. Default 0.6 |
| Can be cut, Grows back in | On/off; 0–600 s (0 never) | Melee swings, blasts and scripts cut it to stubble |
| Shots clip it | On/off | Shots hitting the ground flick the grass aside and, if it can be cut, clip a tuft. Default on |
| Rain weighs it down | 0–1 | |

To vary grass by hand, use the grass brushes in the Landscape workspace. Scripts use
`push_grass(x, y, z, radius)` and `cut_grass(x, y, z, radius)`.

## Example: a cherry orchard in lush grass

You'll design a cherry tree, scatter it over the land and switch the grass to a lush look. Start
from a new project (**File → New project…**); it has no tree designs yet.

1. Open **Window → World & terrain** and select the **Trees** tab.
2. Next to **New tree**, click **Cherry**. A design named after the preset appears and is selected.
3. Under **On the map**, set **Trees per 100 m²** to `4` and click **Only this one**. This creates
   a foliage layer named **Trees** that scatters the cherry design.
4. Select the **Ambience** tab and, under **Grass**, click **Lush** next to **Preset**.
5. Fly over the meadow: cherry trees in four shapes cover the open ground, with taller, deeper green
   grass and flowers beneath them.

To clear a spot, open the Landscape workspace, choose **Paint**, pick **Trees** next to
**Foliage** and use **Erase foliage**.

Do the same from the command line:

```bash
feather-cli --workspace ./orchard command project.create \
  --json '{"name":"Orchard"}' --save project.feather.json

feather-cli --workspace ./orchard --project project.feather.json command tree.upsert \
  --json '{"preset":"cherry","value":{"id":"cherry","name":"Cherry"}}' --save project.feather.json

feather-cli --workspace ./orchard --project project.feather.json command tree.forest \
  --json '{"trees":["cherry"],"density":4}' --save project.feather.json

feather-cli --workspace ./orchard --project project.feather.json command ambience.grass_preset \
  --json '{"preset":"lush"}' --save project.feather.json
```

To grow the orchard only where you paint it, create the layer as `Painted` and paint it in. This
puts a 16 m patch of cherries at X 20, Z −10:

```bash
feather-cli --workspace ./orchard --project project.feather.json command tree.forest \
  --json '{"trees":["cherry"],"layer":"Orchard","density":4,"placement":"Painted"}' \
  --save project.feather.json

feather-cli --workspace ./orchard --project project.feather.json command landscape.stroke \
  --json '{"brushes":[{"mode":"FoliagePaint","foliage_layer":"Orchard","center":[20,-10],"radius":16,"strength":1}]}' \
  --save project.feather.json
```

Check it worked:

```bash
feather-cli --workspace ./orchard --project project.feather.json command tree.get
feather-cli --workspace ./orchard --project project.feather.json command tree.inspect \
  --json '{"id":"cherry"}'
```

`tree.get` lists the `cherry` design with `"canopy": "Puffy"` under `trees`, and a `forests` entry
`{"layer": "Trees", "trees": ["cherry"], "density": 4.0}` (plus `Orchard` if you made it).
`tree.inspect` generates variant 0 and reports its height, about 6 m, and its triangle counts.

## Wind

Wind is a project physics setting. It sways vegetation, blows cloth and smoke, and pushes bodies.
Set the wind vector in metres per second, the gust strength (0–1) and a global foliage sway
multiplier (0–3) with `physics.set`; the weather adds to it during storms. Each foliage layer and
tree design has its own sway multiplier on top. See [Physics](/docs/gameplay/physics/).

## Level of detail

Foliage stays cheap without per-model setup:

- Instances fade out with a dithered dissolve over the last chunk of their view distance, so
  nothing pops in or out. Small foliage fades over a wide band; trees, bushes and rocks over a short one.
- Foliage models use at most two detail levels: full detail near the camera and one simplified level
  beyond it.
- Imported models carry their own detail levels as sibling nodes named `<name>_LOD0`, `_LOD1` and
  so on. Each level shows within a distance band scaled to the model's size and cross-fades into the next.
- Beyond the streamed chunks, the distant land is drawn without foliage. Areas where tree layers grow
  are tinted to read as forest.

## Biomes

Biomes split a level into climate regions such as meadow, forest, highlands and scrub. Two noise
fields, temperature and moisture, give every point a climate; each biome claims a point in that
climate space, and the nearest biomes win, blended at their borders. A biome then shapes the terrain
height and dresses the ground, grass and foliage, and sets footstep sounds and gameplay tags.

1. Open **Window → World & terrain → Biomes**.
2. Start from a set: temperate, wilderness, arid or frozen. A set replaces the biome list and points
   each biome at the level's matching texture layer by name.
3. Tune the **Map**, then each biome. The live preview shows the blended biomes, shaded by height.
4. Add **Regions** to force one biome inside a disc, such as cursed lands around a castle or a safe
   start area.

:::tip
Use the **Flat** landscape base for pure biome terrain. On **Meadow**, the biome height adds on top
of the base.
:::

### Map settings

| Setting | Field | Range | Default |
| --- | --- | --- | --- |
| Enabled | `enabled` | On/off | |
| Seed | `seed` | 0–9,999 in the panel | |
| Patch size | `scale` | 20–5,000 m in the panel, up to 50,000 by command | 700 m |
| Border blend | `blend` | 0 (hard) – 1 (wide) | |
| Ragged borders | `warp` | 0–1 | |

### Biome settings

| Section | Setting | Field | Range |
| --- | --- | --- | --- |
| Climate | Temperature, Moisture | `temperature`, `moisture` | 0 (cold, dry) – 1 (hot, wet) |
| Climate | Weight | `weight` | 0–4; 0 means only regions place it |
| Terrain | Elevation | `elevation` | −100 to 300 m in the panel, −500 to 2,000 by command |
| Terrain | Hill height | `relief` | 0–300 m in the panel, up to 1,000 by command |
| Terrain | Hill size | `roughness` | 4–2,000 m in the panel, up to 10,000 by command |
| Terrain | Ridges | `ridges` | 0 (rolling) – 1 (sharp) |
| Ground | Tint, texture layer, Layer amount | `ground_color`, `ground_layer`, `ground_layer_amount` | Layer 0–3; amount 0–1 |
| Grass | Density, Height, colour | `grass`, `grass_height`, `grass_color` | 0–2; 0.2–3 |
| Foliage | Every layer, per-layer multipliers | `foliage_default`, `foliage` | 0–4; 0 removes the layer here |
| Gameplay | Footstep surface, tags | `surface`, `tags` | grass, dirt, stone, wood, water, snow, metal or sand; up to 8 tags |

Biome presets: meadow, forest, highlands, scrub, lakeland, snowfield, taiga and cursed. A biome's
temperature and moisture also feed the [climate](/docs/world/sky-weather-climate/#climate).

Scripts read biomes with `biome_at(x, z)`, `biome_weight(id, x, z)`, `biome_has_tag(x, z, tag)`
and `biomes()`.

## Limits

- Up to 32 foliage layers per landscape, each with up to 16 models and 16 tree designs.
- Up to 16 biomes and 64 regions per level.
- Foliage view distance is at most 8 chunks (256 m).
- You cannot delete a tree design while a foliage layer scatters it, or a biome while a region places it.

## Automate it

This creates an oak design, scatters it in groves, installs the temperate biome set and checks
the result:

```bash
feather-cli --connect .feather-session.json command tree.upsert \
  --json '{"preset":"oak","value":{"id":"oak","name":"Oak"}}'

feather-cli --connect .feather-session.json command tree.forest \
  --json '{"trees":["oak"],"density":2,"view_chunks":5,"clustering":0.6,"cluster_size":40}'

feather-cli --connect .feather-session.json command biome.set \
  --json '{"preset":"temperate","patch":{"enabled":true,"scale":900}}'

feather-cli --connect .feather-session.json command biome.query \
  --json '{"center":[0,0],"radius":1500,"size":40}'
```

| Command | Purpose |
| --- | --- |
| `landscape.layout` | Replaces foliage layers, among other landscape data |
| `tree.get` / `tree.inspect` | Reads designs; generates one to report its size and triangle counts |
| `tree.upsert` / `tree.remove` | Creates, edits or deletes a tree design |
| `tree.forest` | Creates or updates a foliage layer of tree designs, with optional `clustering` and `cluster_size` |
| `tree.forest_kit` | Plants a forest kit; `density` multiplies every layer (0.1–4, default 1) and `seed` reshuffles placement |
| `tree.bark` | Gives a design a library bark texture |
| `ambience.grass_preset` / `ambience.set` | Applies a grass preset or patches the grass settings |
| `biome.get` / `biome.set` | Reads biomes; sets up the biome map |
| `biome.upsert` / `biome.remove` | Creates, edits or deletes a biome or region |
| `biome.query` | Reports the biome at a point and returns an ASCII map of the layout |
| `physics.set` | Sets the wind, gusts and foliage sway |

To plant a whole layered forest instead, with wildflower grass beneath it:

```bash
feather-cli --connect .feather-session.json command tree.forest_kit \
  --json '{"kit":"woodland","density":1.5}'

feather-cli --connect .feather-session.json command ambience.grass_preset \
  --json '{"preset":"wildflowers"}'
```

The `tree.forest_kit` response lists the layers it planted (`Trees`, `Giants`, `Understory`) with
their densities, and `designs_added` names the designs it created.

See [Agents & automation](/docs/agents/overview/) for connecting a live session.