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.
• The Brush card runs shared validation and reports invalid faces inline. Fatal geometry errors prevent hydration; warnings call out authoring issues that can still render. Reset Cube Brush is the MVP repair path.
• 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.

Vertex, edge, and face selections can be dragged on the viewport floor plane. The editor moves matching duplicated corner vertices across all brush faces so simple cube/prism brushes stay welded, recomputes face planes, and commits one undoable brush edit when the drag releases. Clip mode currently provides element visualization/selection only; split application is future CSG work.

When one or more faces are selected in Face mode, the Brush inspector shows selected-face controls for UV offset, UV scale, UV rotation, material ref, and texture ref. Material and texture rows use Asset Browser-aware picker controls with clear, locate, browse, and compatible drag/drop assignment. These fields edit the persisted BrushFaceDesc data through undoable brush updates. Per-face material batching in hydration is still follow-up work.

Boolean Operations

The command palette exposes brush.subtract, brush.intersect, and brush.merge_convex for selected brush actors. The current implementation is a conservative bounds-based MVP intended for cuboid/prism blockout brushes:

• Intersect replaces the primary selected brush with the overlapping bounds of all selected brushes and deletes the other selected brushes.
• Convex Merge replaces the primary selected brush with the bounding cuboid union and deletes the other selected brushes.
• Subtract clips the primary selected brush to the largest remaining axis-aligned slab after subtracting the second selected brush; the cutter remains in the scene.

These operations commit through history but are not full arbitrary-face CSG yet. Full convex clipping, multi-output subtraction, and material-preserving face matching remain future work.

Current Limits

• Only convex authored faces are supported by the mesh builder.
• Brush diagnostics currently focus on face validity, plane normals, finite vertices, duplicate vertices, degenerate area, and UV scale warnings; a dedicated multi-brush diagnostics window is future work.
• Subtractive brush markers are stored but not automatically evaluated.
• Clip split application and arbitrary-face CSG remain future roadmap work.
• Per-face material and texture refs persist and are editable through Asset Browser-aware controls, but generated brush meshes still hydrate through a single material batch.