Skip to content

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.

Docs and an end-to-end UI test for SubTools

islandmed5cbde876489e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7db28561..3ec5e44f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,18 @@ All notable changes to SculptForge are listed here. The format follows
## [Unreleased]
+### SubTools
+- A scene can hold several meshes (SubTools), like ZBrush: each keeps its own attributes, sculpt layers and undo
+ history. Only the active one is sculpted; the others are drawn slightly dimmed.
+- SubTools panel: select, rename (double-click), show/hide, Solo, Unhide all, reorder, Append (sphere, cube,
+ plane or a model file), Duplicate, Delete, Merge down, Merge visible, Split by polygroups, Split into parts.
+ Alt+click a SubTool in the viewport to select it. New `subtool_*` commands for scripts, Python and MCP agents.
+- Files: projects save every SubTool (format version 2; version 1 projects still open). OBJ (`o` objects), glTF,
+ FBX (an LOD group per SubTool), USD and GoZ export each visible SubTool as its own object, and multi-object
+ files open as SubTools. PLY, STL and splat conversion use the visible SubTools merged.
+- OBJ import: `g` groups now become polygroups (as ZBrush writes them) and `o` objects become SubTools.
+- New cube primitive.
+
### Fixed
- Side panels (Brush Lab, Tools, Generate 3D...) never grow past the bottom of the window. They move up
and scroll instead, so expanded sections such as AI provider are always reachable.
diff --git a/README.md b/README.md
index f9021806..7e918d5e 100644
--- a/README.md
+++ b/README.md
@@ -49,6 +49,7 @@ Plug in Claude, fal.ai or Meshy, or run models entirely on your own machine.
| Gaussian splats, OpenUSD / USDZ | **Built in** | No |
| AI agents (MCP), headless scripting | **Built in** | ZScript |
| Masking, polygroups, visibility (Ctrl / Ctrl+Shift), polypaint, MatCaps | **Yes** | Yes |
+| SubTools (separate meshes: append, split, merge, solo, Alt+click to select) | **Yes** (new) | Yes |
| GoZ exchange with ZBrush | **Yes** (new in 0.2; not yet tested against a live ZBrush) | Yes |
| Multiresolution (subdivision levels), dynamic topology, ZRemesher-class retopology, UV unwrapping | Not yet ([roadmap](ROADMAP.md)) | Yes |
@@ -70,6 +71,10 @@ keep polygroups, mask and polypaint) or as OBJ, FBX or GLB.
respects.
- **Polygroups and visibility** the ZBrush way: auto groups, Ctrl+Shift isolate / hide, rectangle hide, delete
hidden.
+- **SubTools**: keep the body, eyes, teeth and armour as separate meshes, each with its own undo history. You can
+ append a sphere, cube, plane or model file, show/hide, solo, reorder, duplicate, merge and split (by polygroup or
+ by piece), and Alt+click a SubTool to select it. Projects, OBJ, glTF, FBX, USD and GoZ keep them as separate
+ objects.
- **Polypaint** (Paint brush, RGB while sculpting, fills, cavity paint) and six MatCap materials.
- **Project files** (`.sfproj`) that keep everything, with an unsaved-changes prompt, recent files and autosave.
- Unlimited undo, Loop subdivision, **voxel remesh** (DynaMesh-style) and quadric decimation.
@@ -101,7 +106,7 @@ keep polygroups, mask and polypaint) or as OBJ, FBX or GLB.
**ZBrush interchange**
- `.GoZ` import/export with polygroups, mask, polypaint and UVs, and a GoZ bridge (Send / Receive) on Windows and
- macOS. See [docs/goz.md](docs/goz.md); the live bridge hasn't been tested against a running ZBrush yet.
+ macOS. Every visible SubTool goes over as its own ZBrush SubTool. See [docs/goz.md](docs/goz.md); the live bridge hasn't been tested against a running ZBrush yet.
**Gaussian splats**
- Open phone captures (Polycam, Luma, Postshot, Scaniverse and others) as a sculpting reference, convert them
@@ -220,6 +225,7 @@ argument `--mcp`. The agent gets every command as a tool and works on one live s
| Paint / erase mask | Hold **Ctrl** / **Ctrl+Alt** while stroking |
| Invert / clear mask | Ctrl + click / Ctrl + drag on the background |
| Isolate / hide polygroup | Ctrl+Shift + click / Ctrl+Shift+Alt + click |
+| Select a SubTool | Alt + click it |
| Show all | Ctrl+Shift + click on the background |
| Hide outside / inside a rectangle | Ctrl+Shift + drag / Ctrl+Shift+Alt + drag |
| Brush size | `[` / `]` |
diff --git a/ROADMAP.md b/ROADMAP.md
index e35a83a6..36fc21f5 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -78,6 +78,11 @@ retopology, a full ZBrush feature list, rendering/animation (use Blender).
mask by cavity and by polygroup; every brush and polypaint respect the mask
- ✅ Polygroups (auto by normals, by connectivity, from mask, merge visible) and ZBrush-style visibility:
Ctrl+Shift isolate / hide a group, rectangle hide, show all, invert, delete hidden
+- ✅ SubTools: separate meshes in one scene, each with its own undo history; append (primitives or files),
+ duplicate, delete, rename, show/hide, solo, reorder, merge down / merge visible, split by polygroups or pieces,
+ Alt+click to select. Saved in projects (format 2) and exported as separate objects to OBJ, glTF, FBX (an LOD
+ group per SubTool), USD and GoZ; multi-object files open as SubTools
+- ✅ UI tests: `.sfui` scripts drive the real app (clicks, typing, strokes) with screenshots, in CI
- 📋 Multiresolution: subdivision levels you can step up/down while keeping detail
- 📋 Dynamic topology (local remeshing under the brush)
- ✅ Alphas (round, square, noise or any grayscale image) and stroke types (dots, drag-rect, spray, lazy mouse)
diff --git a/tests/ui/subtools_files.sfui b/tests/ui/subtools_files.sfui
new file mode 100644
index 00000000..6820e1fc
--- /dev/null
+++ b/tests/ui/subtools_files.sfui
@@ -0,0 +1,38 @@
+# SubTools survive files: build a scene in the UI, save a project, reopen it, and round-trip GLB / OBJ.
+# Files are written to the working directory (the build folder under ctest).
+run new_sphere subdivisions=4
+click "SubTools/Append"
+click "Cube"
+click "SubTools/Append"
+click "Sphere"
+expect_value subtools == 3
+double_click "SubTools/Sphere 2"
+type "##rename" Eye
+key enter
+expect_text Eye
+click "SubTools/Cube"
+stroke 0.4 0.4 0.6 0.6
+expect_value edited_subtools == 1
+click "SubTools/##eye Eye"
+expect_value visible_subtools == 2
+shot before-save
+
+run save_project path=sf_ui_subtools.sfproj
+run new_sphere subdivisions=2
+expect_value subtools == 1
+run open path=sf_ui_subtools.sfproj
+expect_value subtools == 3
+expect_value visible_subtools == 2
+expect_value active_subtool == 1
+expect_value dirty == 0
+expect_text Eye
+shot reopened
+
+# Exports carry the visible SubTools only; opening the export gives them back as SubTools.
+run export_glb path=sf_ui_subtools.glb
+run open path=sf_ui_subtools.glb
+expect_value subtools == 2
+run save_obj path=sf_ui_subtools.obj
+run open path=sf_ui_subtools.obj
+expect_value subtools == 2
+shot obj-reopened
diff --git a/website/index.html b/website/index.html
index 4503c54e..c27d4d77 100644
--- a/website/index.html
+++ b/website/index.html
@@ -86,6 +86,11 @@
<p>Hold Ctrl to paint a mask, mask by cavity, and grow, shrink or blur it. Auto-group by angle or by
piece, then Ctrl+Shift+click to isolate a group and work on just that part.</p>
</article>
+ <article class="card">
+ <h3>SubTools</h3>
+ <p>Keep the body, eyes, teeth and armour as separate meshes. Append, split, merge and solo them, Alt+click
+ to pick one, and export each as its own object to glTF, FBX, USD or straight back to ZBrush.</p>
+ </article>
<article class="card">
<h3>Polypaint and MatCaps</h3>
<p>Paint colour straight onto the sculpt, tint the cavities, and judge forms under Red Wax, Clay, Skin,