---
name: ferret-physics-terrain
description: Use for ground that changes in Ferret: a layered soil height field you can dig, fill, compact and dump; slopes that slump to their angle of repose, pits that flood, soft ground that swallows heavy bodies, tunnels that hold or cave in, Unreal landscape import.
---

# Terrain

## When to use
Digging, trenches, craters, mud, tunnels, anything where the ground is data.

## The model
A `Terrain` of strata (`Soil`: cohesion, friction angle, bulking, bearing, hardness) on a grid. `dig` takes a footprint, depth and `Tool` (`power`, `reach`); spoil goes to a heap (volume = hole × bulking). Slopes **slump** when the cut is above `criticalHeight` (cohesive soil) or steeper than repose. A water table floods pits. A body sinks when its pressure exceeds the soil's `bearing`. Tunnels need bedrock.

## Steps
1. `new Terrain({ nx, nz, cell, soils: new SoilLibrary(EXAMPLE_SOILS), strata })` or import a landscape.
2. Enable `terrain`; choose a collision mode (sinkage-only, or rebuild meshes after digging).
3. `dig`, `fill`, `compact`, `dump`; read `DigResult.slump`.
4. Hook explosions: `explosions({ terrain })` for craters.
5. Commands: `terrain.at|dig|fill|level|wet|compact|dump`; events `terrain:slump`, `terrain:changed`, `terrain:flooded`.

## Check afterwards
Dig volume equals heap volume divided by bulking; a trench at 90 % of `criticalHeight` stands and at 110 % slumps; dry sand holds no vertical cut.

## What usually goes wrong
- Nothing is removed: tool `reach` below `hardness` (`blocked`), or tiny `power`.
- A pit never slumps: cohesive soil below the critical height; that is correct.
- A body sinks forever: mud with nothing firm beneath.
- `a tunnel needs bedrock`: add a rock stratum.
- Navigation and meshes must rebuild on `terrain:changed`.

## Files

- `reference/terrain.md` — Ground you can dig, dump, fill and compact; slopes that slump, pits that flood, soft soil that swallows heavy things, tunnels that hold or cave in.
- `reference/api-physics-terrain.md` — every export of `@ferret/physics-terrain` with signature and doc comment
- `reference/commands.md` — 7 commands of these packages with their arguments
- `recipes/blasts-and-ground.md` — Seven recipes: danger rings, a crater in sand and in rock, a charge buried too deep, a crater in a real terrain, a wall that shields, an underwater burst, a trench that holds or slumps.