# Terrain Authoring

Terrain is a first-class authored actor backed by `TerrainDesc`. Add it from the Inspector's
**Add Component** shelf by searching for Terrain. It conflicts with other geometry sources on the
same actor: Primitive, Brush, Static Mesh Renderer, and Skinned Mesh Renderer.

## Foundation Workflow

The Terrain card exposes grid resolution, sample spacing, height scale, chunk size, generated
collision, shadows, base material status, and validation. **Resize Flat** deliberately replaces the
height array with a flat grid; normal numeric edits retain all height samples. Every accepted edit is
one reflected history transaction and rebuilds only that terrain's generated chunks.

`assets/levels/terrain_authoring_showcase.scn.ron` is the deterministic foundation fixture. Its 5×5
grid forms an asymmetric hill split into four 2×2-quad chunks. It validates chunk boundaries,
normals, selection through generated children, collider generation, inspector state, and save
stripping without requiring external assets.

## Data And Hydration

- Heights are finite normalized values multiplied by Height Scale at hydration time.
- Sample Spacing controls X/Z distance and the grid remains centered on the actor origin.
- Chunk Size is measured in quads. Neighboring chunks share boundary samples but not runtime mesh
  assets, allowing later stroke updates to rebuild only affected chunks.
- A resolvable shared Material/Material Instance source supplies the chunk material. Missing or
  invalid references produce a warning and visible terrain fallback rather than missing geometry.
- Generated `HydratedTerrainChunk` children own mesh, optional trimesh collider, and shadow state.
  They are runtime-only and never serialized as authored actors.
- Foundation chunks are explicitly excluded from Solari submission and remain raster-visible while
  Auto/Solari is active. Terrain Surface/layer parity enters with the material-layer work in `#24`;
  the editor never substitutes a black or semantically different ray-traced terrain proxy.

Sculpt brushes and grouped stroke undo are tracked by Gitea `#23`; material layers and weight
painting are tracked by `#24`. The persistence decision is recorded in
[ADR 0039](../adr/0039-inline-height-grid-terrain-foundation.md).

Live native-Wayland evidence and focused verification are recorded in the
[terrain foundation evaluation](evaluations/terrain-foundation/).