Blacksite/docs/editor/terrain.md

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.

Live native-Wayland evidence and focused verification are recorded in the terrain foundation evaluation.