# Terrain Authoring Foundation

> **Historical plan — not current implementation guidance.** Use the [documentation index](../../docs/README.md) for current behavior and architecture.

Working implementation plan for Gitea
[`#22`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/22).
This establishes the persistent and hydrated terrain contract required by sculpting `#23`, layer
painting `#24`, physics placement `#25`, and the regression pack `#32`.

## Authored Contract

- Add reflected `TerrainDesc` authoring data with a version, square height-grid resolution, inline
  finite heights, horizontal sample spacing, vertical scale, chunk quad size, optional shared
  Material/Material Instance reference, collider generation, and shadow flags.
- V1 stores the compact height grid in the scene so save/recovery/history/prefab behavior is exact.
  A later external heightmap asset migration must be explicit and versioned rather than silently
  changing ownership.
- Validate resolution, exact sample count, finite values, positive scale, and chunk bounds before
  hydration or publication.

## Hydration

- Partition the grid into deterministic non-overlapping quad chunks with shared boundary samples.
- Generate triangle-list meshes with normals, UVs, U32 indices, and tangents; each generated child
  carries owner/chunk coordinates and remains runtime-only.
- Use the authored shared material when resolvable and an explicit terrain fallback otherwise.
- Optionally attach `ColliderConstructor::TrimeshFromMesh` per chunk.
- Rebuild only the owning terrain's generated chunks when descriptor/material/active state changes;
  disabling/removing terrain cleans every generated child.

## Editor Integration

- Register Terrain as a stable authoring component and ActorKind with conflicts against primitive,
  brush, static renderer, and skinned renderer geometry sources.
- Add an inspector for resolution, world scale, chunk size, collider/shadow state, material summary,
  validation, and a guarded flat-grid resize action. All mutations are one typed history step.
- Include terrain bounds in selection framing and generated chunks in authored-parent picking.
- Expose Add Terrain through the existing component shelf; no new permanent toolbar is added.

## Verification

- Tests cover descriptor validation, deterministic chunk coverage/mesh topology, hydration and
  cleanup, generated-child stripping, serialization, and history round-trip.
- Source-only workspace format/check/strict-Clippy/tests and level validation run. Packaged tests
  remain deferred by project-owner direction.
- Live native-Wayland acceptance creates or loads a terrain actor, verifies chunk rendering and
  selection/inspection, changes scale/chunking, exercises undo/redo, and inspects a saved scene to
  confirm generated chunks are absent.