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.

Sculpt Workflow

Select a terrain actor and enable the mountains button in the existing horizontal viewport toolbar. Choose Raise, Lower, Flatten, Smooth, or Noise, then LMB-drag across the terrain. The radius and strength controls use world meters; the colored footprint follows the sampled terrain surface and identifies the active mode.

Each drag is one stroke and one undo entry, regardless of how many interpolated dabs it contains. Escape or right-click restores the exact pre-stroke height grid; when no stroke is active, either input closes the sculpt tool. Flatten captures the height under the initial press. Smooth samples a stable copy of the current neighborhood per dab, and Noise uses a deterministic per-stroke seed so authored results remain reproducible.

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.

Material layers and weight painting are tracked by Gitea #24. The persistence decision is recorded in ADR 0039.

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