Blacksite/.cursor/plans/terrain_authoring_foundation_2026-07-12.plan.md

Terrain Authoring Foundation

Working implementation plan for Gitea #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.