Free, open-source 3D sculpting for Linux, macOS and Windows: dense meshes, remeshing, painting, built-in AI (image/text to 3D), Send to Unreal, game-ready LODs, Gaussian splats and OpenUSD.
SculptForge UI spec: the shell
Status: design spec, ready to implement. Target: Dear ImGui 1.91.9 (pinned in cmake/Dependencies.cmake, non-docking), SDL3, OpenGL.
0. Goals and non-goals
Sculptors should find their way around within a minute:
- a bounded central canvas, surrounded by shelves that hold the most-used controls (Tab hides them);
- an alphabetical palette bar under the title strip that holds every function; palettes open as drop-downs and can be pinned into the left or right tray;
- Library on
,(comma): a horizontal thumbnail strip along the top of the canvas; - a script console at the bottom;
- Ctrl+hover on any control shows its description and shortcut;
- Customize: Preferences > Config > Customize Shelves, Ctrl+Alt+drag to move or remove items, Save Layout, Reset Layout and Shortcuts (preferences and shortcuts save themselves, #117).
Not goals: free-floating or OS-level detachable panels, tabbed docking, a full keymap editor, a 2.5D canvas. These need ImGui's docking branch or aren't worth the cost (see §12).
The current UI (screenshot, 1600x960) is a menu bar (File/Edit/Mesh/View/Help) plus floating windows over a full-window viewport: Tools (250 px, left), Parts, Layers / Blend Shapes, Game Ready, Brush Lab (open by default, covers the model), and optionally Vertex Paint & Materials, Generate 3D, Gaussian Splats. All of the features stay. Only where they live changes.
2. Target layout
All sizes are logical px at uiScale_ = 1 and get multiplied by uiScale_. Shells are computed every frame from the main viewport; nothing is placed by hand.
2.1 Size table
| Region | Size | Spans |
|---|---|---|
| Title strip | h 24 | full width |
| Palette bar | h 22 (hidden by "Menus" toggle -> 0) | full width |
| Top shelf | h 64 (two rows of 26 + padding) | from left-tray edge to right-tray edge |
| Left shelf | w 88 (tiles 76x76 + 12 label) | between top and bottom shelf |
| Right shelf | w 52 (buttons 44x40, icon + 10 px label) | between top and bottom shelf |
| Bottom shelf | h 78 (Medium tiles; Small h 60, Large h 96 - Preferences > Interface > Shelf tiles) | same span as top shelf |
| Console (closed by default) | h 160, drag 100-400 | above bottom shelf, same span |
| Tray divider | w 8 each side, always visible | top of palette bar to bottom |
| Right tray | w 300 (1600 wide) / 320 (>=1920), drag 240-480 | palette bar bottom to window bottom |
| Left tray | 0 (closed) by default, 300 when open | same |
| Library | h = 28 (tab row) + rows x 118 (96 thumb + 22 label), 1 row default | overlays the top of the canvas, full canvas width |
| Canvas | the rest | 3D view renders only here |
2.2 1600 x 960 (default, right tray open, left tray closed)
x:0 8 96 1240 1292 1300 1600
+-------------------------------------------------------------------------------------------------------------+ y0
|SF SculptForge head.sfproj* | Verts 5.1k Tris 10.2k Part Sphere Layer Base status msg... [QS][1][2][3][Menus][? Search F3]|
+-------------------------------------------------------------------------------------------------------------+ y24
|Alpha Brush Color Draw Edit File Generate Help Material Preferences Render Script Splats Stroke Tool Transform |
+--+-------------------------------------------------------------------------------------+-+-------------------+ y46
| |[Library] [Sculpt|Paint] [Add|Sub] [Rgb] [Size 60 ====] [Strength 0.50 ====] | | Tool [x] |
| |[AI Brush] [Front] [ X | Y | Z sym ] [Pressure>Str] [Pressure>Size] 5.1k / 10.2k | | Sphere 5.1k (o) |
+--+------+--------------------------------------------------------------------+---------+ | [Open][Save][Imp] |
|d | +--+ | | [Frame] |d| > Part (open) |
|i | |Br| | | [Move ] |i| Sphere eye |
|v | +--+ | | [Zoom ] |v| Helmet eye |
| |Clay | | [Rotat] | | [Append][Dup]...|
| | +--+ | | [Persp] | | > Layers |
| | |St| | CANVAS | [Floor] | | > Geometry |
| | +--+ | (3D view, gradient bg) | [Wire] | | > Remesh |
| |Dots | 1144 x 790 | [Grps ] | | > Masking |
| | +--+ | | [Mask ] | | > Face groups |
| | |Al| | | [Paint] | | > Visibility |
| | +--+ | | [Solo ] | | > Export |
| |Round | | [Splat] | | > Display |
| | +--+ | | | | |
| | |Mt| | | | | |
| | +--+ | | | | |
| |Studio| | | | |
| |[colr]| | | | |
| |[sw|sw| | | | |
+--+------+--------------------------------------------------------------------+---------+ | | y900
| | (o) (o) (o) (o) (o) (o) (o) (o) (o) (o) (o) (o) (o) (o) [+] | | |
| |Std Clay ClayB DamSt Move Smth Infl Pnch Trim Snake Layer Nudge Paint ... | | |
+--+-------------------------------------------------------------------------------------+-+-------------------+ y960
Canvas = x 96..1240, y 110..900 (1144 x 790). With Library open (1 row), it covers y 110..256 of the canvas. With the console open, the canvas bottom moves to y 740.
2.3 1920 x 1080
Same structure. The right tray is 320 wide (x 1600..1920), the divider is at 1592, and the right shelf is at 1540..1592. Canvas = x 96..1540, y 110..1020 (1444 x 910). The extra width goes to the canvas only. Shelves keep their fixed sizes.
2.4 Narrow windows (< 1280 logical px wide)
The right tray auto-collapses to its divider. Palettes are then used as drop-downs only. Left-shelf tiles shrink to 60. The bottom shelf scrolls sideways (mouse wheel).
2.5 Canvas ownership (important engineering change)
Today renderer_.draw(camera_, fbW, fbH, ...) fills the window, and picking and the brush cursor use window coordinates. The shell introduces:
// App.h (shell section)
struct CanvasRect { float x, y, w, h; }; // logical px, window coordinates
CanvasRect canvasRect() const; // from Layout, recomputed every frame
Renderer::draw(...)gets a viewport rect (glViewport/glScissorto the canvas in framebuffer pixels).camera_.aspect = w/hof the canvas.pick,onMouseDown/Move, the brush cursor,onScreen,hide_rectand face group overlays all convert window -> canvas coordinates in one helper.- Mouse events outside the canvas never start strokes or orbits, even when ImGui doesn't capture them (e.g. on gaps between shelf items).
- Recording,
--render, demos andhideUi_keep using the full window (canvasRect()returns the whole viewport whenhideUi_is set). - The area outside the canvas is cleared to
shellBg. The canvas itself has a neutral charcoal background with a soft radial vignette (no coloured gradient) and gets a 1 px#0e0e10border.
3. Contents of every region, mapped to SculptForge
Notation: cmd:name = CommandRegistry command, act:id = UI action (§8), widget:x = custom widget.
3.1 Title strip (h 24)
Left to right:
- App glyph + "SculptForge".
- Document name +
*whendoc.dirty. Click: Save. - Info readout (dim text):
Verts 5.1k Tris 10.2k Part <name> (2/5) Layer <name|Base> 60 fps. Splat count when splats are loaded. - Status message (
status_), elided. Errors in orange-red for 6 s. - Right-aligned:
[QuickSave]:act:file.quicksavewrites a timestamped.sfprojto<user lib>/QuickSave/, keeping the last 10. It shows up in the Library Snapshots tab.- Layout preset buttons
[1][2][3](§9.3). [Menus]toggles the palette bar.- A search field showing "Search F3" that opens the command palette (§7).
3.2 Palette bar (h 22): alphabetical, every function
Each name is a button. A click opens the palette as a drop-down window under its name (an ImGui popup, width 300, max height = window - 60, scrolls). The palette header row has the tray icon (Lucide panel-right; Shift+click it to go left), the palette title and a close button. Clicking the icon moves the palette into the right tray, and you can also drag the icon onto a tray. A palette that is already in a tray shows its name in accent colour, and clicking the name scrolls the tray to it and flashes it.
Every palette's body is one function void drawPalette_<Id>(), and the same function draws it in a drop-down or in a tray.
| Palette | Contents (existing code it comes from) |
|---|---|
| Alpha | Large preview; built-in grid (round, square, noise); Load image...; Invert loaded image; recent alphas. (PanelBrushes.cpp alpha section, cmd:brush_set_alpha) |
| Brush | Brush grid (the same widget as the picker, §4.1); Custom brushes list; Brush Lab (AI)... button; recipe editor for the active custom brush (drawRecipeEditor); Save brush... / Load brush... (cmd:brush_save, cmd:brush_load); Front faces only; Invert (Alt) |
| Color | Vertex Paint colour picker and swatches; Fill object (cmd:paint_fill); Clear (cmd:paint_clear); From cavity (cmd:paint_from_cavity); Pick under cursor (C). (PanelVertexPaint.cpp minus the material part) |
| Draw | Size, Strength (Intensity), Add/Sub, Rgb (paintRgb_), Paint mode, Tablet: Pressure > strength, Pressure > size, pen readout |
| Edit | Undo |
| File | New Sphere, New Plane, Open..., Open Recent >, Save, Save As..., Autosave interval; Import/Export: Export OBJ, GLB (blend shapes), LOD chain, USD/USDZ, FBX for Unreal, Send to Unreal, Save Splats...; Bridge >; Quit. (Today's File menu, drawFileMenuProjectItems, drawBridgeMenu) |
| Generate | Generate 3D (image/text -> 3D, ComfyUI) opens the existing Generate 3D window; Image Relief / Inflate / Project (cmd:image_relief, image_inflate, image_project); AI provider settings (drawAiSettings) |
| Help | Controls (shortcut sheet generated from the Action registry), User Guide (Shift+F1), What's New (also opened once after each update), Command palette (F3), Website & documentation, Report a problem, About SculptForge |
| Material | Studio + Lit Sphere thumbnail grid (cmd:set_material); base colour (today's "Material" ColorEdit in Tools) |
| Preferences | Sub-palettes: Config (Customize Shelves, Save Layout, Revert to Saved Layout, Reset Layout and Shortcuts, Export Interface..., Import Interface... Ctrl+L); Interface (UI scale, Ctrl+hover help, Plain tooltips delay, One sub-palette open, Left-handed layout); Library (library folder, Show at startup, Startup rows, Placement top/bottom); Hotkeys (list with reset; Store); Tablet (pen, pressure meter, test area, pressure curve, eraser and side-button mappings; see docs/tablet.md); Autosave |
| Render | Wireframe (Shift+F), Show Mesh, Show Vertex Paint, Show Mask, Show Face Groups, Show Splats, Frame Model (F) (today's View menu render toggles) |
| Script | Show console (`), Run script file..., Copy session as script, Clear console |
| Splats | drawSplatSection body (info, clean, transform, to mesh, save, clear) |
| Stroke | Stroke type (Dots, Drag Stamp, Spray, Lazy Stroke) and its settings (spray scatter, lazy radius) |
| Tool | The model palette. Header: active Part name + tri count, [Open] [Save] [Import]. Sub-palettes (collapsing headers, one open at a time, Shift+click for more): Part (Parts panel body), Layers (Layers / Blend Shapes body), Geometry (Lower Level / Higher Level, Level slider, Remove Below / Remove Above, Rebuild Lower Levels, Divide Ctrl+D + Smooth, Subdivide, Decimate, cmd:decimate), Remesh (Voxel remesh + resolution, the "voxel remesh" analogue), Masking (drawMaskingSection), Face Groups (drawFaceGroupsSection), Visibility (Show all, Invert visibility, Remove Hidden), Export (Game Ready panel body: LODs, Unreal, GLB/LOD chain), Display (wireframe, show mask/groups, material colour) |
| Transform | Draw / Move / Scale / Rotate (Q W E R, Gizmo: pivot, World / Surface axes, Mask, All Parts, Falloff, numeric entry; cmd:transform), Symmetry X / Y / Z (X), Frame (F), Solo (cmd:part_solo), Wireframe |
Part / Layer / Masking / Face Groups are Tool sub-palettes, not top-level palettes. The Mesh and View menus disappear, and their items move to Tool > Geometry/Remesh and Render. Palettes are sorted by name at registration, so a new palette lands in alphabetical order automatically.
3.3 Top shelf (h 64, two rows)
Row 1:
[LibraryBrowser](act:ui.library,,)[Sculpt | Paint](paintMode_)[Raise | Lower](invertToggle_)[Rgb](paintRgb_)[Vertex | Texture]paint target (act:draw.paint_vertex,act:draw.paint_texture; contextual: only when the Part has a texture)Size 60slider (w 180;radiusPx_,S)Strength 0.50slider (w 180;strength_,I)
Row 2:
[AI Brush](toggles the Brush Lab window)[Front](front faces only)[Dynamic]dynamic topology (act:draw.dynamic) andDetail 50slider (w 120; contextual: only while Dynamic is on)[X][Y][Z]symmetry (Xtoggles X)[Pressure>Str] [Pressure>Size]- right-aligned
5.1k / 10.2k(ActivePoints / TotalPoints analogue: visible vs total tris)
Contextual controls. A shelf button that only applies in some situations (the Vertex / Texture paint target needs a texture, Splats needs a capture, Detail needs Dynamic on) is hidden while it doesn't apply, rather than shown greyed out, so the shelves don't fill with dead buttons. Customize mode shows them all so they can be moved or removed. Palette entries stay visible and disabled (with the reason in Ctrl help), because palettes are where users look things up.
Sliders put the label inside the frame (SliderFloat("##size", ..., "Size %.0f")), and the grab is a thin accent bar.
3.4 Left shelf (w 88)
A vertical stack of thumbnail tiles (76x76, label under). A click opens the pop-up picker beside the tile (§4):
- Brush: current brush thumbnail + name. Picker §4.1.
- Stroke: icon for Dots / Drag Stamp / Spray / Lazy Stroke. Picker = 4 tiles + settings.
- Alpha: alpha preview (today's 48 px preview). Picker = alpha grid + Load image.
- Material: lit sphere sphere. Picker = material grid.
- Colour: a 76x76 SV square + hue strip (
ImGui::ColorPicker3withNoSidePreview|NoInputs|NoLabel, width 76), then two swatches (primary / secondary, a click swaps them, like "Alternate"), then[Fill](cmd:paint_fill).
A Texture slot is left out (no texture feature yet). It's reserved in the layout data so it can be added later.
3.5 Right shelf (w 52)
Icon + tiny label, 44x40 each. Groups are separated by 8 px.
- Navigation: Frame (F). Move, Zoom and Rotate are drag buttons: left-drag on the button pans / zooms / orbits the camera. Implement with
InvisibleButton+IsItemActive()+io.MouseDelta, feeding the existing camera functions. - View: Persp (only if the camera supports ortho; otherwise leave it out), Floor (optional grid, only if cheap), Wire = wireframe (Shift+F; W is the Gizmo's Move since 0.5), Groups (
showFaceGroups), Mask (showMask), Paint (showVertexPaint). - Object: Solo (
cmd:part_solo), Splats (show splats; shown only when splats are loaded).
Toggles that are on get an accent background.
3.6 Bottom shelf (h 78, Medium tiles): quick brushes
Default contents, in order: Standard, Clay, Clay Block, Sharp Crease, Move, Smooth, Inflate, Pinch, Flatten, Crease, Trim, Tendril, Layer, Nudge, Paint. Then any custom brushes the user adds, and a [+] tile that opens the brush picker in "add to shelf" mode.
Tiles are 40 px brush thumbnails with the name under them. The active brush gets an accent outline. Hotkey digits (1-9, 0) are drawn small in the tile's top-left. Right-click a tile: "Remove from shelf", "Assign shortcut...". Right-click in the brush picker: "Add to bottom shelf".
3.7 Right tray (default) / left tray (empty by default)
- Right tray default stack: Tool (Parts sub-palette open).
- Trays scroll vertically. Palette headers are full-width bars (h 22,
#2e2e32) with the tray icon (click returns the palette to the bar), the title and a collapse arrow. - Divider: 8 px. Click or double-click toggles the tray, and dragging resizes it (cursor
ResizeEW). It draws a 2 px grip in its centre. - With Preferences > Interface > "Auto Collapse", opening one palette in a tray collapses the others when they'd overflow (default: on for the left tray, off for the right).
3.8 Floating windows that stay floating
Brush Lab, Generate 3D, About, Controls, project / Part confirmation pop-ups. They keep their current ImGui windows and their imgui.ini persistence. Two changes: Brush Lab defaults to closed, opened from the top-shelf [AI Brush] or Brush palette. Its first-use position is the canvas top-left + (16,16), so it no longer sits over the model at 1600x960.
4. Pop-up pickers
All pickers are ImGui pop-up windows (BeginPopup). They open next to the shelf tile that opened them (to its right, top-aligned), or under the mouse when opened from a key. They close on pick, Esc, or a click outside. Tiles are 64x64 + 16 label, 6 px gap, 6 columns (max width ~460), with section headers ("Built-in", "Custom", "Library").
4.1 Brush picker (B, or click the Brush tile)
- A "Recent" row of the last 8 brushes at the top.
- Grid sections: Built-in (the 14
BrushTypes + Paint), Custom (doc.brushesrecipes, with AI-made ones marked by a small sparkle badge), Library (.sfbrushfiles in<user lib>/Brushesthat aren't loaded yet; picking one runscmd:brush_load). - Type-to-filter. The first letter typed keeps only brushes whose name starts with it, and the grid shows letter-index chips A-Z with counts at the top. Each remaining tile then shows an orange key badge: the shortest next letter that tells it apart (Standard after S ->
T, Tendril ->N, Smooth ->M). Pressing that letter picks the brush.- If no prefix matches, fall back to a substring match (shown in a filter field at the top).
- Backspace undoes one letter. Enter picks the first match.
- Thumbnails come from §6 (fallback: Lucide glyph + name).
- Hover: help box, meaning a 192 px thumbnail and the brush description (recipe
description). With Ctrl held you get the standard Ctrl help. - Right-click a tile: Add to bottom shelf / Assign shortcut... / Save as .sfbrush... / Delete (custom only).
4.2 Stroke, Alpha and Material pickers
- Same tile grid, no letter badges (few items), but typing still filters.
- Material is also opened with M (currently unbound in SculptForge).
- Hovering a material tile previews it on the model : set
renderSettings_.litspheretemporarily and restore it on leave.
4.3 Size / Strength at cursor
S and I open a one-slider pop-up under the mouse ("Size 60", 200 px wide, already focused for drag or typing). It closes on release, Enter or Esc. [ and ] keep working.
4.4 Optional: Space quick menu (P2)
Holding Space shows a compact panel under the cursor: Brush / Stroke / Alpha / Material tiles + Size + Strength. Releasing Space closes it. Only do this if time allows. It's the Quick Menu.
5. Library (,)
5.1 Layout
- An overlay window anchored to the top edge of the canvas, full canvas width,
NoDecoration|NoMove|NoSavedSettings, background#141416at 96%. Preference "Placement: bottom" anchors it above the bottom shelf instead. - Header row (h 28): tabs (text buttons, active = accent underline):
Project | Tool | Brush | Alpha | Material | Image | Splats | Snapshots | Recentthen back / forward arrows (tab+folder history), a breadcrumb (User > Tools > creatures), a filter field (w 160), the rows selector[1][2][3][4],[Open folder...](picks a folder and adds it as a library root), and close. - Strip: tiles 96x96 + 22 label (elided, full name in hover). Tiles flow top-to-bottom within the row count, then left to right, so the strip scrolls horizontally.
- The mouse wheel scrolls sideways.
- Left-drag on empty space or a tile scrubs. Drag starts after 4 px, so a click is still a click.
- The first tile in a sub-folder is the up-folder tile. Folders show a folder glyph and are entered with a double-click.
- Hover: 1.5x scale glow and full path. Ctrl+hover shows Ctrl help with file size, modified date and (for meshes) the cached triangle count.
5.2 Sources (what SculptForge shows)
Library roots:
- Built-in: assets shipped with the app.
assets/demo/*(lion-head.glb, teddy-sketch.png), built-in brushes, built-in alphas, lit spheres, primitives. - User:
SDL_GetUserFolder(SDL_FOLDER_DOCUMENTS)/SculptForge/, created on first run withProjects/ Tools/ Brushes/ Alphas/ Images/ Splats/ QuickSave/. The Preferences > Library "library folder" setting overrides it.
Each tab shows a "Built-in" and a "User" folder at its root.
| Tab | Shows | Double-click | Other actions |
|---|---|---|---|
| Project | *.sfproj in User/Projects + recentFiles_ projects |
open (via confirmDiscard) |
|
| Tool | meshes .obj .glb .gltf .fbx .stl .ply .usda .usdz Bridge + built-in primitives Sphere, Plane, Cube (makeCube exists) + demo lion |
open (replace scene, with confirmDiscard) |
Shift+double-click = append as Part (cmd:part_append) |
| Brush | built-in brush types, doc.brushes, .sfbrush files |
activate / cmd:brush_load |
|
| Alpha | round/square/noise + images in User/Alphas | cmd:brush_set_alpha |
|
| Material | Studio + every lit sphere | cmd:set_material |
|
| Image | images in User/Images + demo sketch | small menu: Generate 3D... / Relief / Inflate / Project onto model / Use as alpha | |
| Splats | .ply .splat captures, splat .glb |
cmd:open (loads as reference) |
|
| Snapshots | Snapshot + autosave files, newest first | open | |
| Recent | recentFiles_ (all kinds) |
open |
- Right-click any tile: Open / Append as Part (meshes) / Show in file manager (
SDL_OpenURL("file://...")) / Refresh thumbnail. - Dragging a tile onto the canvas = double-click.
- Directory listing runs on a worker thread and is re-scanned when a tab opens and every 5 s while Library is open (cheap
last_write_timecheck). - Preferences > Library > "Show at startup" defaults on, opening the Project tab. It's forced off for
--ui-test,--render, recording and demos.
6. Thumbnails
ThumbnailCache gives every visual asset an ImTextureID:
- Meshes and projects: rendered offscreen. Use
Renderer::renderToImage, or a newRenderer::renderMeshThumbnail(const Mesh&, litsphere, size, rgba&)ifrenderToImageis tied to the synced scene. Size 192x192 (displayed at 96, crisp on HiDPI), the default material (Soft Clay), transparent background, camera framed on the bounds from a 3/4 front view (yaw 30, pitch 15).- Mesh loading uses the existing importers on a worker thread. GL rendering happens on the main thread, at most 2 thumbnails per frame.
- Projects:
saveProjectalso writesthumbnail.png(256x256, current camera) into the.sfprojZIP. The Library reads that instead of loading the whole project. Older projects without it are loaded on the worker and rendered once.
- Brushes: on a worker, sculpt a mark of each brush's own shape on the front of a fresh clay ball (icosphere, subdivided 6 times) using the same
Sculptor/recipe code as real strokes, so brushes tell apart at shelf size: Standard an S, Clay three strips, Clay Block a hash of bars, Sharp Crease a diagonal cut, Crease a curved groove, Inflate a puffed ring, Pinch a sharp chevron, Smooth a bumpy ridge smoothed on one half, Flatten a planed dome, Trim a cut-down ridge, Layer a raised square frame, Nudge an upright ridge slid sideways, Move and Tendril pulls at the silhouette, recipes an S. The ball fills 97% of the tile. Every brush, Paint included, is the same ball, camera and material (Soft Clay), so the shelf reads as one icon set. Key = brush type or recipe JSON hash pluskThumbnailVersion(bump it whenever thumbnails are made differently, so stale disk-cached ones are remade). - Alphas: the alpha's samples, from the tile's charcoal (none) to the clay's lit grey (full effect), not white on black.
- Materials: the same ball as the brushes, rendered with that lit sphere. Pickers list the default (Soft Clay) first (
litsphereInListOrder), then the others, then Studio. - Images: stb-decoded, downscaled to 192.
- Disk cache:
<prefDir>/thumbs/<fnv1a64(kind|absPath|size|mtime|version)>.png(stb_image_write is in third_party). In-memory LRU of 256 GL textures. - Placeholder: while a thumbnail is pending, the tile shows the Lucide glyph for its kind (
box,brush,circle-dashed,palette,image,sparkles,folder) on#2a2a2e.
7. Ctrl-hover help, command palette, console
7.1 Ctrl-hover help ("Ctrl+hover help")
- Trigger: an item is hovered (
ImGuiHoveredFlags_AllowWhenDisabled) and Ctrl is held. No delay while Ctrl is down. Preferences > Interface > Ctrl+hover help (default on). - Ctrl+Alt+hover shows the alternate page: the command's parameter list (name, type, description, required), i.e. the scripting reference.
- Plain hover without Ctrl: only icon-only buttons and elided labels get a small tooltip (label + shortcut) after 0.5 s. All other text tooltips that exist today (e.g. custom-brush description, Voxel remesh) move into the Ctrl help.
- Look (tooltip window, width 340, padding 10, rounding 6, bg
#18181aat 97%, 1 px border accent at 60% alpha):
Keycaps: rounded rect+------------------------------------------------------+ | [icon] Subdivide [Ctrl]+[D] | <- SemiBold 15, shortcut keycaps right |------------------------------------------------------| | Smoothly subdivide the mesh (Loop subdivision). | <- Regular 14, #c8c8c8, wrapped | Each level multiplies the triangle count by 4. | | | | Tool > Geometry subdivide | <- 12 px dim path left, command name right (mono) +------------------------------------------------------+#2c2c30, 1 px#4a4a50, text accent. Placement: cursor + (18, 18), flipped to stay inside the viewport. - Text sources: Action description (§8). For command-backed actions this is
Command::description, so it stays in sync with the AI tool schema and CLI help. Non-action widgets (sliders, checkboxes) useui::HelpText(...). Every interactive item in shelves, palettes and pickers must have help; a UI test checks a sample.
7.2 Command palette (F3, also Ctrl+Shift+P; the title-strip search field)
- A modal-less pop-up at the top centre of the canvas, width 560, max 12 rows.
- Fuzzy search over all Actions: label (weight 3), palette path (2), id / command name (2), description words (1). Brushes and materials are actions too ("Brush: Clay", "Material: Chrome").
- Rows: icon, label, dim palette path, right-aligned shortcut. Disabled actions are shown dimmed, with the reason in Ctrl help.
- Empty query: the 8 most recently used actions (persisted).
- Keys: Up/Down, Enter runs, Esc closes.
- Shift+Enter on a command with parameters opens the console with
namepre-typed. - Commands with required parameters always go to the console instead of running.
- Shift+Enter on a command with parameters opens the console with
7.3 Console ( ` toggles it, Script palette)
- Bottom strip above the bottom shelf, h 160 (drag the top edge, 100-400). Font: ImGui's built-in ProggyClean via
AddFontDefault()(MIT, ships inside ImGui, no new file) at 13 x scale. - Log: every
App::runCommand(UI, keys, palette, AI agent, MCP) echoes as a script line followed by its result:
Status messages that aren't commands appear dim.> subdivide Subdivided: 40,962 vertices, 81,920 triangles > remesh resolution=200 [AI] > brush_create name="Dragon Scales" ... ! open path="missing.obj" -> Could not open ... (red) - Input: one line, parsed with
parseScript(core/Script.h), so;and multiple statements work.- Tab completes command names, then
param=names; a second Tab lists the candidates. - Up/Down walks history (last 200, persisted to
<prefDir>/console_history.txt). - Typing
helporhelp <cmd>prints descriptions;?= help.
- Tab completes command names, then
- Buttons: Run script... (a text file of statements), Copy session as script (puts the echoed commands on the clipboard, which makes it a macro recorder), Clear.
- This needs
std::string formatStatement(const std::string& name, const Args&)incore/Script(quotes strings containing spaces,true/false,%gnumbers), the inverse ofparseScript. Add a round-trip unit test.
8. Actions and shortcuts (the glue)
One registry drives shelves, palettes, help, the command palette, keys and customization.
// src/app/Actions.h
struct Action {
std::string id; // "geometry.subdivide", "ui.library", "brush.clay", "view.wireframe"
std::string label; // "Subdivide"
const char* icon = nullptr; // ICON_LC_* or nullptr
std::string description; // shown in Ctrl help; defaults to Command::description
std::string palette; // "Tool > Geometry" (help footer, command palette)
std::string shortcut; // default chord, e.g. "Ctrl+D", "Shift+F", ","; "" = none
std::string command; // CommandRegistry name when the action runs a command
std::function<void()> run;
std::function<bool()> checked; // toggles; null = not a toggle
std::function<bool()> enabled; // null = always
};
class ActionRegistry {
public:
void add(Action a); // replaces by id
const Action* find(std::string_view id) const;
const std::vector<Action>& all() const;
bool handleKey(SDL_Keycode, SDL_Keymod); // true if consumed (respects io.WantCaptureKeyboard / WantTextInput)
std::string shortcutText(std::string_view id) const; // effective chord, after user overrides
void setShortcut(std::string_view id, std::string chord); // user override ("" clears)
Json overridesToJson() const; void overridesFromJson(const Json&);
void touch(std::string_view id); // MRU for the command palette
};
// Every CommandRegistry command without required params is auto-registered as "cmd.<name>".
UI helpers that every panel uses (so help and customization come for free):
// src/app/Ui.h
namespace sf::ui {
enum class Look { Label, Icon, IconLabel, Tile };
bool ActionButton(App&, const char* actionId, ImVec2 size = {}, Look = Look::Label); // runs the action on click;
// toggles draw accent when checked(); Ctrl help; Ctrl+Alt drag source in customize mode
void HelpText(const char* title, const char* shortcut, const char* description, const char* path = nullptr); // for the last item
void HelpAction(const char* actionId); // for the last item
bool SliderInside(const char* id, float* v, float lo, float hi, const char* fmt, ImGuiSliderFlags = 0); // label inside the frame
}
Default shortcut map. Existing bindings are kept, new ones are added, and nothing existing changes meaning:
| Key | Action | Key | Action | |
|---|---|---|---|---|
, |
Library | B |
Brush picker | |
Tab |
Hide/show shelves (+ trays) | M |
Material picker | |
` |
Console | S / I |
Size / Strength at cursor | |
F3, Ctrl+Shift+P |
Command palette | Shift+F |
Wireframe (W until 0.4; since 0.5 Q W E R are Draw and the Gizmo's Move, Scale, Rotate) |
|
Ctrl+L |
Import Interface... | |||
F1 |
Controls | 1-9, 0, [ ] X F P C, Ctrl+D/Z/Y/O/S/N/E/U/V |
unchanged |
onKey's switch becomes actions_.handleKey(...) with these defaults. The F1 Controls window is generated from the registry, grouped by palette. User overrides save themselves in ui.json (#117).
Optional (P2): shortcut assignment in place. Ctrl+Alt+click any ActionButton, then press a key ("Press a key for 'Clay'... Esc cancels"). Conflicts reassign.
9. Customize, Save Layout, Restore
9.1 Layout data (the shared contract)
// src/app/UiLayout.h
struct UiLayout {
int version = 1;
bool shelvesVisible = true, paletteBarVisible = true, leftHanded = false;
bool leftTrayOpen = false, rightTrayOpen = true;
float leftTrayWidth = 300, rightTrayWidth = 300; // logical px
std::vector<std::string> leftTray, rightTray; // palette ids, top to bottom
std::vector<std::string> openSubpalettes; // "tool.part", ...
std::vector<std::string> topShelf, leftShelf, rightShelf, bottomShelf; // item ids: action ids, "widget.*", "sep", "row" (top shelf line break)
bool consoleOpen = false; float consoleHeight = 160;
bool libraryOpen = false; int libraryRows = 1; std::string libraryTab = "project"; bool libraryBottom = false;
bool customize = false; // runtime only, never stored
};
UiLayout standardLayout(); // the built-in default described in §3
Json toJson(const UiLayout&); bool fromJson(const Json&, UiLayout&, std::string& err); // unknown ids are dropped, not fatal
9.2 Behaviour
- Preferences > Config > Customize Shelves sets
customize. While it's on, the shelves draw a dashed 1 px outline and the status line says "Customize: Ctrl+Alt+drag to move or remove items". - Ctrl+Alt+drag any ActionButton or shelf widget. It works from palettes and pickers too, which is how you add an item to a shelf.
- ImGui drag source, payload
"SF_UIITEM"={ itemId, fromShelf, fromIndex }. - Shelves draw insertion targets between items (2 px accent line).
- Dropping anywhere that isn't a shelf (e.g. the canvas) removes the item if it came from a shelf.
- Palettes can't be dropped on shelves, only into trays (
"SF_PALETTE"payload from the palette header icon).
- ImGui drag source, payload
<prefDir>/ui.json={ layout, shortcuts: overrides, prefs: {popupInfo, uiScale, oneSubpalette, autoCollapse, library...}, radialMenus }. The shortcuts, prefs and radial menus save themselves (#117):App::autosavePrefslooks every 0.25 s while frames are drawn, writes 0.5 s after a change (temp file + rename) and once more at quit. The layout in it is the one Save Layout kept (storedLayout_; none yet: the standard one).config.store(Ctrl+Shift+I before 0.11.1) is now Save Preferences Now, without a key, so old keymaps naming it still load.- Reset Layout and Shortcuts:
layout_ = standardLayout(), shortcut overrides and radial menus cleared; the layout isn't kept until Save Layout. - Revert to Saved Layout: reload
ui.json. - Export Interface... / Import Interface... (Ctrl+L): the same JSON at a chosen path (for sharing layouts).
- At startup
ui.jsonis loaded if it's there, otherwise the standard layout.--ui-test,--renderand recording always use the standard layout (deterministic tests and videos). - The layout is never saved automatically (the preferences are). So nobody is surprised, the first time the layout changes in a session (tray moved, shelf edited) the status line hints once: "Layout changed - Preferences > Config > Save Layout keeps it".
9.3 Presets (title-strip [1][2][3])
- Standard (§2).
- Sculpt: trays closed, shelves on, Library off. Maximum canvas.
- Wide: left tray open with Brush + Stroke + Alpha, right tray Tool + Material.
Clicking a preset applies it (layout only). Save Layout makes it stick.
10. Theme
Keep the existing orange accent, but only for one thing per group: the current tool or mode (ui::IsModeAction). Everything else is charcoal grey. Put this in applyStyle() (to be moved to src/app/Theme.cpp) as named constants:
| Token | Value | Use |
|---|---|---|
shellBg |
#1b1b1d |
shelves, trays, title strip, area around the canvas |
panelBg |
#222225 |
palette drop-downs, tray contents, pop-ups (WindowBg, PopupBg at 98%) |
header |
#2b2b2f / hover #37373c |
palette and sub-palette headers |
frame |
#28282c / hover #323237 |
slider and input frames |
button |
#333337 / hover #414146 / pressed #4e4e55 |
buttons |
accent |
#f0882e (hover #ff9a45) |
the current tool or mode of a group (bg accent, text #ffffff): Draw/Move/Scale/Rotate, Sculpt/Paint, the brush, Mask Pen/Lasso Mask...; the 2 px underline of an option that is on; a slider bar only while dragging; Library active tab |
toggleOff |
#29292e (hover #36363c), text textOff #b4b4b9 (6.9:1) |
options that are off: a dark chip with a readable label, so off never looks disabled (disabled is faded by alpha) |
toggleOn |
#4c4c53 (hover #58585f), text textBright #f2f2f2 |
options that are on (X, Rgb, Pressure > Strength, Mask, Menus): raised grey with a 2 px accent underline (a side bar on the right shelf), never a solid accent fill. Also the chosen side of a choice (ui::IsChoiceAction: Add | Sub), without the underline |
trough |
#2c2c31 |
unselected segments of a mode or choice group |
selection |
#3a3a41 (active #45454c) |
selected list rows (ImGuiCol_Header): a lighter neutral row, with a 2 px accent bar on the left where the list draws one |
sliderFill / sliderBar |
white 9% / #85858c |
the filled part of a SliderInside and the thin bar along its bottom (accent while dragging); plain slider grabs are sliderBar too |
checkMark / checkBorder |
#e6e6e8 / #55555c |
check marks (neutral); the outline of an unchecked box (ui::Checkbox) |
text / textOff / textDim |
#d8d8d8 / #b4b4b9 / #8c8c90 |
|
border |
#111113 |
1 px between regions |
danger |
#e5604a |
errors |
| canvas | neutral charcoal, soft radial vignette (kBgFS); 1 px #0e0e10 frame; vignette down to shellBg at the edges (no step at the seams); default material Soft Clay (matte warm grey: a steep upper-left key, a fill from the right, a warm ground bounce, a broad sheen along ridges and a cool rim on the lower right; light cavity, only above a smooth sphere's own curvature) |
Style:
- Rounding:
WindowRounding 0(shells),PopupRounding 6,FrameRounding 3,GrabRounding 2. - Spacing:
FramePadding (6,3),ItemSpacing (4,4),ItemInnerSpacing (4,4). ScrollbarSize 10,GrabMinSize 6.- Top shelf hierarchy, by meaning: every item is the full row height in the 15 px font, so both rows share one baseline. Modes (Draw | Move | Scale | Rotate, Sculpt | Paint) and choices (Add | Sub) are 1 px-gap segments on
trough; options (Front, Dynamic, X/Y/Z, Rgb, Pressure...) are separatetoggleOffchips; Library / AI Brush plain buttons. The ActiveTris / TotalTris readout is one 12 px line on the row's centre line. The Draw palette uses the same looks (Pressure toggles are buttons there too) and 12 px dim section labels with a hairline. - Title strip: Snapshot, 1 2 3 and Menus are
toggleOffchips; the readout is 12 pxtextDim, the status message 15 pxtextBrightso it stands out. - Palette drop-downs open below the top shelf (under the palette bar when Tab hides the shelves), never over the tool rows.
- Font: Inter Regular 15 x scale (as now). Shelf labels and tile captions 12 px (a second Inter size), help titles Inter SemiBold 15, console ProggyClean 13.
- Trays (helpers in
src/app/Palettes.h): two header levels only. A palette header is a filled bar (icon, bold title, chevron at the right). A sub-palette header is 22 px and quiet: title 8 px in, chevron at the right, no fill until hovered or open, an opaque hairline under it, no accent. The open section's content is indented 8 px (tray::Section), so it lines up with the header title. A group inside a section ("Project", "Quad Remesh", "Tablet") istray::GroupLabel: 12 pxtextDimflush with the content, then a hairline; notImGui::SeparatorText. - Tray controls: every slider is a
ui::SliderInside(ints throughtray::SliderInt), never a stock grab over its label. Check marks in palettes are the text colour (tray::Style), not the accent. A row of controls fills the line in equal halves or thirds; a number beside a button is a drag field of the same size (no tiny - / + buttons). The active row of a list (Parts) is a lighter neutral (white ~9%) with a 2 px accent bar on its left, in a recessed well with no outline. Helper text is 12 pxtextDim. - The left tray's colour field is drawn by hand (
App::drawColorWidget, Pickers.cpp): a rounded saturation/value square with a ring marker, a 10 px hue strip with a thin bar marker that stays inside its ends, and the main/second swatches as equal halves with a 1 px edge. One 4 px gap between all of them. The default main colour is a mid grey (second: white), so the swatches are neutral until the user picks a colour.
10.1 Looks and the SculptForge layout (Preferences > Interface > Look)
The tokens above are the Classic look (still the default). Three more looks give SculptForge its own face; each
is a real theme, not a paint-over: theme::applyLook() (src/app/Theme.cpp) sets every token from a looks::Palette
(src/app/LookSchemes.h: crust, mantle, base, surface0-2, overlay, subtext, text, bright, accent, accent2, red, green,
yellow) and a theme::LookStyle that the shell reads (tiles, gap, corner radii, monospace, status bar and header
styles, effects). Widgets keep reading theme::* tokens; hand-drawn corner radii go through theme::rounding().
The cube logo keeps the SculptForge orange (theme::brand) in every look; the accent never uses it otherwise.
| Look | Feel | Specifics |
|---|---|---|
| Forge Terminal | a tiling window manager (Hyprland, Omarchy) | every region is a tile: 6 px gaps over a darker wallpaper, a 1 px border, 2 px in the accent on the tile under the pointer (focus follows the mouse); square corners, flat fills; JetBrains Mono for captions, headers, readouts and slider numbers (Inter stays for body text); palette headers with an accent rule; a Waybar-style status bar. Seven schemes: Tokyo Night (default), Catppuccin Mocha, Gruvbox Dark, Nord, Rosé Pine, Kanagawa, Everforest. Match my desktop theme (Linux; shown only when an Omarchy theme is found) reads colors.toml (or alacritty.toml) from ~/.config/omarchy/current/theme or ~/.local/state/omarchy/current/theme, never writes. |
| Phosphor | a CRT terminal | green (P1) or amber (P3) on near-black; monospace everywhere; [ TOOL ]──── headers, [+] / [-] sections, ── Group ── rules (box-drawing); inverse-video mode and menu; optional scanlines and a glow around the focused tile, on the interface only (never the 3D view), off by default. |
| Blueprint | engineering paper / CAD | deep Prussian blue, cyan and white line work; drafting grid in the gaps and palette headers, registration marks at tile corners, dimension-line section rules; the status bar as a drawing's title block (MODE SCULPT │ BRUSH Clay │ TRIS 47.2k); technical monospace numbers. |
Every look also tints the 3D view's gradient (RenderSettings::gradientCentre / gradientEdge); a flat background the
user picked is left alone.
Layouts. Picking one of the three looks switches to the SculptForge layout; the old one stays as the
Classic layout (Preferences > Interface > Look > Layout, ui_look layout=classic), and works with any look.
- Status bar (h 30): the cube and name, the task menus File · Edit · Sculpt · Paint · Mesh · View · Render · Help, the status message, then modules (mode, brush, file, triangles, fps), the presets 1 2 3 as workspaces, search (F3), minimise and close. No palette bar.
- Task menus (
taskMenus(), Palettes.cpp) hold whole palettes as sections, so every item has exactly one place: File (File, Script), Edit (Edit, Preferences), Sculpt (Brush, Draw & Tablet, Stroke, Alpha, Symmetry & Gizmo), Paint (Vertex Paint & Color), Mesh (Parts & Geometry = Tool, Generate 3D), View (Display = Render), Render (Materials, Gaussian Splats), Help. A menu drops down with its sections on the left and the chosen one beside them, under its usual header (the tray icon still pins it). A section already in a tray is skipped (clicking it flashes the tray).ui.palette.*, F3 and old scripts still open any palette, inside its menu. - Tool shelf: one row (Sculpt | Paint, Draw | Move | Scale | Rotate, Add | Sub, Rgb, Size, Intensity, Dynamic, X Y Z R). Library, Brush Lab, Front and the pressure options moved to the menus (Sculpt > Draw & Tablet, View > Display) and F3; the triangle counts to the status bar. Left, right and bottom shelves as before.
- Tiles (
ShellMetrics::gap, ShellGeometry.cpp): every region is inset by half the gap after growing by it, so its contents keep their size; the dividers become the gaps beside the trays.
Scripts and tests: ui_look look=forge|phosphor|blueprint|classic scheme=nord phosphor=amber effects=true layout=sculptforge|classic; expect_value look, shell_layout; tests/ui/looks.sfui; screenshots for choosing:
tools/looks/shots.sfui.
11. Icons: recommendation = Lucide icon font merged into ImGui
- Licence: Lucide is ISC ("Copyright (c) Lucide Icons and Contributors"). The icons derived from Feather are MIT ("Copyright (c) 2013-present Cole Bemis"). Both notices must ship with copies, so add both texts to
THIRD_PARTY_NOTICES.mdand the About dialog ("Lucide icons (ISC/MIT)"). Both are GPL-3.0-compatible. [R15] - Why Lucide over Material Symbols (Apache-2.0):
- Lucide's codepoints are all in the BMP.
IconsLucide.hdefinesICON_MIN_LC 0xe038andICON_MAX_16_LC == ICON_MAX_LC 0xe6fd, so it works with ImGui's default 16-bitImWchar. - The TTF is small (a few hundred KB).
- Thin outline glyphs suit a dense UI.
- Material Symbols is a 10 MB+ variable font. Its full range goes past 16-bit (IconFontCppHeaders has a separate
ICON_MAX_16_MS), and Apache-2.0 adds NOTICE handling. [R16][R17]
- Lucide's codepoints are all in the BMP.
- Files (vendored, pinned to one
lucide-staticversion; codepoints aren't stable across versions, so header and TTF must come from the same version):assets/fonts/lucide.ttffromhttps://unpkg.com/lucide-static@<pinned>/font/lucide.ttfthird_party/IconFontCppHeaders/IconsLucide.h(zlib licence), regenerated by that repo'sGenerateIconFontCppHeaders.pyfrom the same version'slucide.css
- Embedding: add
lucide.ttfto the existingembed_files(... EmbeddedFonts.cpp sf::assets ...)in CMake. After adding Inter Regular inApp::init:
Repeat the merge for the 12 px shelf font. In the right shelf, use a separate non-merged 20 px Lucide font for the large icons.static const ImWchar kIconRanges[] = {ICON_MIN_LC, ICON_MAX_16_LC, 0}; ImFontConfig ic; ic.MergeMode = true; ic.PixelSnapH = true; ic.FontDataOwnedByAtlas = false; ic.GlyphMinAdvanceX = 15.0f * scale; ic.GlyphOffset = ImVec2(0, 2.0f * scale); io.Fonts->AddFontFromMemoryTTF((void*)assets::fontLucide, int(assets::fontLucide_size), 15.0f * scale, &ic, kIconRanges);- With ImGui >= 1.92 (dynamic fonts), the glyph ranges can be dropped. Not relevant on 1.91.9.
- Glyphs to use (check each name against the pinned header):
brush, paintbrush, spray-can, move-3d, rotate-3d, scale-3d, scan (frame), hand (pan), zoom-in, grid-3x3 (wireframe), eye, eye-off, boxes (parts), layers, droplet (mask), shapes (facegroups), palette (color), circle-dashed (alpha), sun (material), image, folder, folder-open, save, undo-2, redo-2, search, square-terminal, circle-help, settings, sparkles (AI), wand-sparkles, package (export), gamepad-2 (game ready), panel-left, panel-right, chevron-*, x. - Sculpt-specific visuals (brushes, alphas, materials, models) use rendered thumbnails (§6), not glyphs. No icon set has good sculpting-brush icons.
12. ImGui constraints (non-docking 1.91.9)
Works without the docking branch:
- Fixed shells as windows with
NoDecoration|NoMove|NoResize|NoSavedSettings|NoBringToFrontOnFocus|NoScrollWithMouse(trays scroll inside a child), placed every frame. - Tray and console resize via
InvisibleButtonsplitters. - Palette drop-downs, pickers and the command palette as pop-ups.
- Customize drag and drop via
BeginDragDropSource/Target.
Each shell window needs NoFocusOnAppearing and must not steal keyboard focus, so onKey still gets keys. Draw order: shells first, then Library, then floating windows, then pop-ups and help.
Needs the docking branch (flagged, not planned): dragging panels out into separate OS windows (multi-viewport); arbitrary tabbed or split docking of palettes; ImGui-native persistence of dock layouts.
13. Implementation: phase 0 + three parallel workstreams
Phase 0: contracts (one small commit, ~half a day, before splitting)
Create these with real declarations and stub implementations, so all three streams compile and merge independently:
src/app/Actions.h/.cpp:Action,ActionRegistry(stubhandleKeyreturns false). App memberActionRegistry actions_.src/app/Ui.h/.cpp:ui::ActionButton(stub =ImGui::Button(label)+ run),ui::HelpText/HelpAction(stubs no-op),ui::SliderInside.src/app/UiLayout.h/.cpp: struct +standardLayout()+ JSON. App memberUiLayout layout_.src/app/LibraryBrowser.h:class LibraryBrowser { void draw(App&, CanvasRect); bool open; void toggle(); }.src/app/Thumbnails.h:class ThumbnailCache { ImTextureID brush(int type); ImTextureID recipe(const BrushRecipe&); ImTextureID alpha(const BrushAlpha&); ImTextureID material(int litsphere); ImTextureID file(const std::string& path); void pump(Renderer&); }. All stubs return 0 / draw nothing.src/app/Pickers.h:enum class Picker { Brush, Stroke, Alpha, Material }; void openPicker(Picker, ImVec2 anchor); void drawPickers(App&);- Lucide font + header embedded and merged (§11), the
ICON_LC_*macros available. App.h: three clearly fenced member sections,// ---- Shell (A) ----,// ---- LibraryBrowser (B) ----,// ---- Help/Console/Config (C) ----. Each stream adds members only inside its own section.
Workstream A: shell, layout, palettes, theme
Owns: src/app/Shell.cpp (new: title strip, palette bar, shelves, trays, splitters, layout math, canvasRect()), src/app/Palettes.cpp (new: palette registry, drawPalette_* for all 16 palettes, Tool sub-palettes), src/app/Theme.cpp (moved applyStyle + tokens), the existing Panel*.cpp (converted to draw*Contents() without Begin/End), App.cpp drawUi/drawMenuBar (removed)/drawToolPanel (removed)/panel functions, the canvas-rect changes in run/handleEvent/pick/brush cursor, and src/render/Renderer.* (viewport rect param).
Delivers: §2, §3 (except the picker internals), §9.1 runtime use (reads and edits layout_, Ctrl+Alt drag/drop targets on shelves and trays), §9.3 presets, §10. Registers the Actions for everything it draws (brush., view., ui.toggle_shelves, ui.palette....). Uses ui::ActionButton everywhere.
Tests: rewrite tests/ui/*.sfui steps that clicked View-menu items or old window titles. Item labels stay the same wherever possible: "Brush Lab/..." stays a floating window with the same name, and Parts buttons keep their labels inside Tool > Parts. Add tests/ui/shell_layout.sfui (shots at 1600x960 and 1920x1080, Tab hides shelves, tray divider toggle, palette into tray).
Workstream B: Library, thumbnails, pickers
Owns: src/app/LibraryBrowser.cpp, src/app/Thumbnails.cpp, src/app/Pickers.cpp, src/app/AssetLibrary.h/.cpp (folder roots, worker-thread scanning), src/core/Project.cpp (+ thumbnail.png in .sfproj, read helper loadProjectThumbnail(path, Image&)), and maybe a Renderer::renderMeshThumbnail (coordinate the signature with A, who owns Renderer.*; B adds the new method in a separate block).
Delivers: §4 (brush picker with letter badges, stroke/alpha/material pickers, S/I sliders, material hover preview), §5, §6, Snapshot target folder. Registers ui.library (,), ui.picker.brush (B), ui.picker.material (M), ui.size_popup (S), ui.strength_popup (I), file.quicksave.
Interface used by A: the left-shelf tiles call thumbs.brush(...) etc. and openPicker(Picker::X, tileRectMax). The bottom shelf uses thumbs.brush/recipe. The Brush/Alpha/Material palettes reuse drawBrushGrid(App&, GridMode) exported from Pickers.h.
Tests: tests/ui/library.sfui (key , -> expect "Library", tab switch, double-click the "Sphere" tile -> triangles changed, Shift+double-click -> parts == 2), the brush picker (key b, key s, key t -> Standard active), unit tests for the cache key and the project-thumbnail round-trip.
Workstream C: help, command palette, console, config, keys
Owns: src/app/Actions.cpp (real handleKey, chord parsing, overrides, MRU, auto-registering commands), src/app/Ui.cpp (real Ctrl-hover help rendering, customize-mode drag sources inside ActionButton), src/app/CommandPalette.cpp, src/app/Console.cpp, src/app/Config.cpp (Store/Restore/Load/Export Interface, ui.json, preferences values), src/core/Script.* (formatStatement + test), App::onKey (replaced by actions_.handleKey), the one-line echo hook in App::runCommand, and the generated F1 Controls window. Also src/app/UiTest.cpp key aliases (comma, backtick, tab, f3), and a test step expect_help TEXT (the Ctrl-help box shown this frame contains TEXT).
Delivers: §7, §8, §9.2. Registers ui.command_palette, ui.console, config.store (Ctrl+Shift+I), config.restore_standard, config.restore_custom, config.load (Ctrl+L), config.save, config.customize. Provides drawPalette_Preferences_Config content for A's Preferences palette (A calls config::drawConfigSection(App&) and config::drawInterfaceSection(App&) from Config.h).
Tests: tests/ui/help_console.sfui (hold ctrl + hover Subdivide -> expect_help "Loop subdivision"; key f3, type "Command palette" subdiv, key enter -> triangles x4; key ` + type remesh resolution=64 + enter -> expect_text "> remesh"; Save Layout writes ui.json in the isolated settings dir; Reset Layout and Shortcuts restores tray state).
Overlap and merge order
- The only shared files are
App.h(fenced sections),App.cpp(A: drawUi and panels; C:onKey, a one-linerunCommandhook; B: none),Renderer.*(A owns, B adds one method) andCMakeLists.txt(each stream appends its own sources to one list; trivial conflicts). - Merge order: Phase 0 -> C -> B -> A. A rewires the most call sites, so it merges last against real helpers. A can still develop fully against the stubs.
- Each stream adds the new
.cppfiles toCMakeLists.txt, runs the unit tests plus./build/sculptforge --ui-test tests/ui/<file>.sfui, and attaches 1600x960 and 1920x1080 shots to its PR.
Acceptance checklist (whole feature)
- The default UI at 1600x960 matches §2.2. The canvas is clear of floating windows.
- Every former menu item and panel control is reachable from a palette. The command palette finds every command.
- Ctrl+hover shows description + shortcut on every shelf, palette and picker item.
-
,/B/M/Tab/`/F3/Ctrl+Shift+Iwork. Existing shortcuts are unchanged. - Customize: Ctrl+Alt drag adds, moves and removes shelf items; Save Layout persists across restarts (tests/ui/prefs_autosave.sfui); Reset Layout and Shortcuts resets.
- Library shows thumbnails for every tab within ~1 s of opening (cached afterwards). Double-click loads; Shift+double-click appends a Part.
- Tests,
--renderand demo recordings are unchanged (standard layout, full-window canvas whenhideUi_). - Lucide ISC + MIT notices are in THIRD_PARTY_NOTICES.md and About.
References
- [R15] Lucide licence: https://lucide.dev/license
- [R16] IconFontCppHeaders (zlib; IconsLucide.h, ImGui merge example): https://github.com/juliettef/IconFontCppHeaders
- [R17] Material Symbols guide (Apache-2.0): https://developers.google.com/fonts/docs/material_symbols
- Dear ImGui font merging: https://github.com/ocornut/imgui/blob/v1.91.9/docs/FONTS.md