Packs and macros

A pack is one file (.sfpack) that brings brushes, alphas, Lit Spheres, Material Recipes, VDM brushes, keymaps, pie menus and macros at once. A macro is a list of SculptForge commands you can run with one click, one key or one pie-menu slot. Both are plain data: SculptForge never runs code from a pack or a macro.

Install a pack#

Use File > Install Pack..., drop a .sfpack file on the window, or click Install Pack... in Library > Packs. Nothing is installed yet: a review shows exactly what is inside first.

Click Install to add it, or Cancel to leave everything as it was. When a pack fails a check, the review says which file and why (for example "../evil.sfbrush" leaves its folder), and nothing is installed.

Installed packs live in SculptForge's own data folder, each in its own folder. A pack never replaces a built-in brush or one of your own: a pack brush called like an existing one shows the pack's name after its own, for example Clay (Supporter Pack).

Where pack items show up#

Keymaps and pie menus change how SculptForge responds, so they are only applied when you click Apply keymap or Add pie menu. Store Config keeps the result.

Library > Packs#

Open the Library (,) and click Packs. Each installed pack has a row:

• The check box turns the pack off or on. Off, its items leave every list; nothing is deleted.
• Details shows its description, folder, keymaps, pie menus and macros.
• Remove deletes the pack and everything it brought. Your own files are never touched.

Start SculptForge with --no-packs to leave every pack out for one session (safe mode), for example to check whether a problem comes from a pack. sculptforge-cli --no-packs does the same for scripts.

Make a pack#

Library > Packs > New Pack... lists what you made yourself: brushes in your library, images in your Library's Alphas and MatCaps folders, the active Part's Fill layers as a Material Recipe, your VDMs, your pie menus, your changed shortcuts (as a keymap) and your macros. Tick what goes in, fill in the name, author, license and description, and click Save Pack.... The file is checked exactly as an install would check it before it is written.

Tick Supporter Pack (insider channel) for a pack meant for supporters. It only changes the label shown in the review and the pack list; anyone can install the file.

To build a pack from a folder in a script, lay the folder out like a pack (brushes/, alphas/, matcaps/, materials/, vdms/, keymaps/, piemenus/, macros/, plus LICENSE.txt and preview.png) and run:

sculptforge-cli -c 'pack_create folder=MyPack path=MyPack.sfpack id=my-pack name="My Pack" author=Me license=CC-BY-4.0'

The file format is described in the pack format.

Record a macro#

1. In Library > Packs, click Record Macro. A red Recording macro note shows at the top of the window.
2. Work as usual: every command you run from a menu, a button, the console or a script line is kept.
3. Click Stop Recording. The Macro Editor opens with the commands; give the macro a name and click Save.

Commands a macro may not run (see below) are left out, and the status line says how many. A file inside the project folder is kept as a path relative to it; any other file becomes ?, which asks for a file when the macro runs.

Write or change a macro#

Macro Editor (in Library > Packs, or F3) is a plain text editor. A macro is the command language of the console and sculptforge-cli, one command per line, # for comments:

# name: Clean Up Scan
# description: Remesh, smooth and export a GLB next to the project
remesh resolution=256
mask_clear
export_glb path=exports/clean.glb

The line under the text checks it as you type: every command must exist, be allowed in a macro and have the values it needs. Save writes it to your macros folder; Run runs it.

Run a macro#

Every saved macro (yours and those of enabled packs) is an action:

• F3: type its name and press Enter.
• Preferences > Hotkeys: find it with the filter and give it a key, like any other action (see Assign shortcuts).
• Preferences > Input > Radial Menus: put it in a pie menu slot.
• Library > Packs: Run next to your macros, or in a pack's Details.

The first time a macro runs, SculptForge shows its whole command list and asks. Click Run to go on; you are not asked again for that macro unless its text changes. A macro's edits on one Part are one undo step (Ctrl+Z takes back the whole macro).

What a macro can do#

A macro only runs SculptForge's own commands, in order. It can't run programs or scripts, and it can't:

• reach the network (AI services, the brush gallery, Unreal, the phone link) or send to Blender, Maya or ZBrush;
• install, remove or switch packs, or run another macro;
• name a file outside the project folder. File values are either a path inside the folder of the saved project (exports/clean.glb) or ?, which opens a file dialog when the macro runs. Absolute paths, .., ~ and drive letters are refused.

Save the project first when a macro uses relative paths: they are relative to the project's folder.

Scripts and Python#

The same rules apply outside the app:

In Python, sculptforge.run(doc, "pack_install", path="Pack.sfpack") and the other commands work the same way. A command you type into sculptforge-cli or Python is your own explicit request, so it runs without the confirmation the app shows. AI agents connected through sculptforge-cli --mcp can't install, remove or switch packs.