Blacksite/docs/editor/brushes.md

Brush Authoring

Brushes are persisted blockout geometry stored as ActorKind::Brush + BrushDesc.

MVP Scope

• BrushDesc::default() creates an additive cube brush.
• Each face stores a stable ID, plane, vertices, optional material/texture refs, UV offset/scale/rotation, and smoothing group.
• Hydration builds generated mesh children from active brush components and strips those children before scene save.
• Brush actors validate separately from primitives and imported/static mesh actors.
• The Actor Inspector Add Component shelf can add a Brush component. The Brush card exposes kind, face count, shadow flags, and cube reset.
• Draw Brush mode (B, toolbar pencil, or command brush.draw) creates additive prism brushes from snapped floor points. LMB places points, Backspace removes the last point, Enter commits through undo history, and Esc/right-click cancels without scene mutation.

Element Modes

With a brush actor selected, 1/2/3/4 enter vertex, edge, face, and clip modes. Element modes show viewport overlays for the selected brush, route LMB to element picking, support Shift+LMB multi-select, and display a Brush: <mode> badge. Esc returns to object mode.

The current slice selects elements and visualizes handles; mutating vertices/faces and committing drag edits through history is the next implementation layer.

Current Limits

• Only convex authored faces are supported by the mesh builder.
• Subtractive brushes are stored as markers but are not evaluated as CSG.
• Face, edge, vertex, clipping, and primitive brush creation tools are future roadmap work.