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

Terrain Sculpt Tools (#23)

Historical plan — not current implementation guidance. Use the documentation index for current behavior and architecture.

Scope

• Add a modal terrain sculpt operator for raise, lower, flatten, smooth, and deterministic noise.
• Keep activation and brush settings in the existing horizontal viewport toolbar.
• Track a terrain-local cursor hit and render a world-space brush footprint preview.
• Apply live stroke previews while preserving one history entry per completed stroke.
• Restore the exact pre-stroke height grid on Escape or right-click.

Implementation

1. Add pure heightfield sampling, ray-hit, falloff, and brush-dab functions with focused tests.
2. Add editor-only terrain sculpt state and viewport input/preview systems.
3. Commit strokes through the reflected component transaction after restoring the pre-stroke snapshot.
4. Add compact terrain controls to the existing viewport toolbar and update operator hints.
5. Document controls and validation evidence in the terrain editor guide and root checklist.

Acceptance

• All five modes visibly modify terrain.
• The brush ring follows the actual terrain surface.
• Escape and right-click cancel without dirtying history.
• Mouse release creates exactly one undoable transaction regardless of dab count.
• Formatting, editor/shared checks, focused tests, and live editor QA pass.