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.
C++ 3d3d-sculptingcppdear-imguidigital-sculptingfbxgame-developmentgaussian-splattinggltfimage-to-3dmcpopenglopenusdsculptingtext-to-3dunreal-engine
// SculptForge - open source digital sculpting
// SPDX-License-Identifier: GPL-3.0-or-later
#include "app/App.h"
#include "app/Bench.h"
#include "app/Calibration.h"
#include "app/CrashLog.h"
#include "app/OptimisticBench.h"
#include "app/UiServe.h"
#include "ai/AiPolicy.h"
#include "core/Benchmark.h"
#include "core/ExitWatchdog.h"
#include "core/Wavelet.h"
#include "core/FocusDetail.h"
#include "core/Pack.h"
#include "core/StudioProfile.h"
#include <SDL3/SDL_main.h>
#include <algorithm>
#include <chrono>
#include <cstdio>
#include <cstdlib>
#include <filesystem>
#include <memory>
#include <stdexcept>
#include <string>
#include <vector>
#ifndef _WIN32
#include <unistd.h> // execv (--cli)
#endif
namespace {
void usage() {
std::puts(
"Usage: sculptforge [model / splats / image file] [options]\n"
"\n"
" --run \"<commands>\" Run commands at start-up (see sculptforge-cli --list)\n"
" --render out.png Render headless and exit (thumbnails, review sheets)\n"
" --turntable N With --render: N frames around the model (out_000.png ...)\n"
" --size WxH Render size (default 1024x1024)\n"
" --measure-idle S Sit idle, print the frames drawn per second over S seconds, exit\n"
" (SF_CONTINUOUS_REDRAW=1 draws every frame, as before 0.9.5)\n"
" --measure-stroke S[,R] Draw a fast scripted circle stroke for S seconds (brush radius R px),\n"
" e.g. after --run \"new_sphere\"; print how far the dabs left the circle and the frame times, exit\n"
" (SF_STROKE_IMMEDIATE=1 places every dab at once, as before 0.9.6)\n"
" --view YAW,PITCH Camera angles in degrees (default -30,-15)\n"
" --zoom F Move the camera F times closer than the framed view (default 1)\n"
" --wireframe Render with wireframe overlay\n"
" --facegroups Render with face group colours\n"
" --hide-mesh Render only the Gaussian splats\n"
" --demo NAME Play a scripted demo (sculpt, image-to-3d, brush-lab, game-ready, splats)\n"
" --record out.mp4 Record the demo offscreen to a video (needs ffmpeg) and exit\n"
" --demo-asset FILE Image or model the demo opens\n"
" --demo-output FILE Save the demo's result (e.g. creature.glb)\n"
" --fps N Recording frame rate (default 30)\n"
" --supersample N Render recordings N times larger and downsample (sharper, allows zoom-ins)\n"
" --ui-test FILE.sfui Run a UI test script headless and exit (0 = pass); settings are isolated\n"
" --ui-out DIR Where UI tests save screenshots\n"
" --ui-record out.mp4 Also record the UI test, every frame in real time with the pointer drawn (needs ffmpeg)\n"
" --ui-serve [--threads N] Warm UI test server: one window, then one test per stdin line (tools/test/warm_ui.py)\n"
" --fullscreen Start filling the screen (F11 toggles)\n"
" --no-ai Start with every AI feature off and locked (as SF_AI=off)\n"
" --no-packs Safe mode: start without any installed pack (Library > Packs)\n"
" --studio FILE Start in studio mode with this studio profile (studio.json; docs/studios.md)\n"
" --offline Studio mode without a profile: no outside connection at all\n"
" --blender Load what the Blender add-on sent (it starts SculptForge this way)\n"
" --bench Run the performance benchmark (with GPU upload and orbit timings) and exit\n"
" --bench-sizes 4,16,32 Benchmark sizes in millions of triangles\n"
" --bench-dabs N Dabs per benchmark stroke (default 40)\n"
" --bench-brushes TEXT Only the benchmark brushes whose name contains TEXT (e.g. large)\n"
" --bench-no-project Skip the project save / open (it needs twice the memory)\n"
" --bench-view Benchmark only what the viewport costs (uploads, orbit)\n"
" --bench-dyntopo Benchmark dynamic topology strokes (e.g. --bench-sizes 0.25,1,4)\n"
" --bench-micro Benchmark micro-displacement levels (sizes = micro triangles, e.g. 33,100,300)\n"
" --bench-micro-level N Micro level for --bench-micro (default 4: 256 per base triangle)\n"
" --bench-out FILE Write the benchmark report (Markdown) to FILE\n"
" --calibrate Measure this computer (GPU, CPU, memory; about 2-3 s), print the hardware\n"
" profile as JSON and save it (add --calibrate-quick, --calibrate-no-save)\n"
" --timelapse out.mp4 Render the opened project's history (saved beside it as .sfhist) as a\n"
" turntable timelapse and exit (--size 3840x2160 for 4K, --fps N)\n"
" --timelapse-seconds S Length of the timelapse (default 20)\n"
" --benchmark Proof mode: a scripted stroke on 5M / 20M / 33M (and 100M when memory\n"
" allows) triangle meshes through the input handlers, with a live HUD; writes a\n"
" JSON result and an MP4 of the run and exits (docs/benchmark.md)\n"
" --benchmark standard-15m The standard scene: a 15M triangle head, Clay S/M/L, Move, Smooth and a 240 px\n"
" brush (standard-33m: 33M; standard: both). The numbers on sculptforge.app/benchmarks\n"
" --benchmark standard-1b Experimental Focus Detail: a billion micro triangle head streamed from disk\n"
" --benchmark core-200m Research: a 200 million micro triangle head in memory (open, strokes, orbit)\n"
" --benchmark core-100m The same at 100 million micro triangles\n"
" --benchmark-file PATH Open the project PATH, then the same strokes and orbit\n"
" --benchmark-script T.sfui Play a take (a UI test script's strokes, orbits, keys and waits) in real time\n"
" with the HUD; writes an MP4 and a per-frame CSV (frame ms, stroke lag) and exits.\n"
" A project to open goes after it: --benchmark-script take.sfui head.sfproj\n"
" --focus-detail FILE Experimental: open a Focus Detail file (.sfdetail)\n"
" --benchmark-sizes 5,20 Proof mode mesh sizes in millions of triangles\n"
" --benchmark-out FILE Where the JSON result goes (default: sculptforge-benchmark-<time>.json here)\n"
" --benchmark-video FILE Where the MP4 goes; --benchmark-no-video records none\n"
" --benchmark-vsync Keep vertical sync on (default off: frame times are not capped)\n"
" --benchmark-seconds S Length of each scripted stroke (default 6)\n"
" --log-dir DIR Write sculptforge.log to DIR instead of the user data folder\n"
" --crash-test KIND Crash on purpose (segv, abort or throw) to test the crash note in the log");
}
// UI tests must never read or change the user's real settings, recent files or
// autosaves: point the per-user data directories at a fresh temporary folder.
std::filesystem::path g_isolatedDir; // isolateSettings' folder, removed when the run ends well
void isolateSettings() {
if (!g_isolatedDir.empty()) return; // (once: --run with --measure-stroke asks twice)
std::error_code ec;
const auto dir = std::filesystem::temp_directory_path(ec) /
("sculptforge-ui-test-" + std::to_string(std::chrono::steady_clock::now().time_since_epoch().count()));
std::filesystem::create_directories(dir, ec);
g_isolatedDir = dir;
const std::string d = dir.string();
#if defined(_WIN32)
_putenv_s("APPDATA", d.c_str());
_wputenv_s(L"SF_USER_DATA_DIR", dir.c_str()); // (SDL_GetPrefPath ignores APPDATA: app/UserData.h; wide, any name)
_putenv_s("SF_AI_LIVE_DIR", d.c_str()); // live mode's pipe (link/AiLink.h): never the user's window's
#else
setenv("XDG_DATA_HOME", d.c_str(), 1);
setenv("XDG_CONFIG_HOME", d.c_str(), 1);
setenv("HOST_XDG_DATA_HOME", d.c_str(), 1); // in a Flatpak, the Blender bridge folder (io/BlenderBridge.h)
setenv("SF_AI_LIVE_DIR", d.c_str(), 1); // live mode's socket (link/AiLink.h): never the user's window's
#if defined(__APPLE__)
setenv("HOME", d.c_str(), 1);
#endif
#endif
for (const char* key : {"ANTHROPIC_API_KEY", "OPENAI_API_KEY", "HF_TOKEN", "HUGGING_FACE_HUB_TOKEN", "FAL_KEY", "MESHY_API_KEY"}) {
#if defined(_WIN32)
_putenv_s(key, "");
#else
unsetenv(key);
#endif
}
}
// Runs by an agent or a script (SDL_APP_ID=sculptforge-agent, as ~/Work/CLAUDE.md asks for agent windows, or a
// Claude Code shell) never touch the user's settings, log or hardware profile: a benchmark or render started there
// wrote into the user's sculptforge.log and pushed the session's log to sculptforge-previous.log.
// SF_ISOLATE=1 isolates any run, SF_ISOLATE=0 none of the automatic ones.
bool automatedRun() {
const char* force = std::getenv("SF_ISOLATE");
if (force && *force) return *force != '0';
const char* appId = std::getenv("SDL_APP_ID");
const char* claude = std::getenv("CLAUDECODE");
return (appId && std::string(appId) == "sculptforge-agent") || (claude && *claude);
}
int finishIsolated(int code) {
// The isolated folder (settings, the log, autosaves: a benchmark's 33M mesh is over a gigabyte) goes with a run
// that passed; a failed one keeps it, log included, to look at.
if (g_isolatedDir.empty()) return code;
std::error_code ec;
if (code == 0) {
std::filesystem::remove_all(g_isolatedDir, ec);
if (ec) std::fprintf(stderr, "sculptforge: couldn't remove the test folder %s: %s\n", g_isolatedDir.string().c_str(), ec.message().c_str());
} else {
std::fprintf(stderr, "sculptforge: exit %d, test folder kept for a look: %s\n", code, g_isolatedDir.string().c_str());
}
return code;
}
} // namespace
// --crash-test: crash the way real bugs do, after the log has started.
[[noreturn]] static void crashOnPurpose(const std::string& kind) {
sf::crashlog::quietSystemCrashDialog();
sf::crashlog::action("crash_test " + kind);
if (kind == "abort") std::abort();
if (kind == "throw") throw std::runtime_error("crash test");
volatile int* nowhere = nullptr;
*nowhere = 1;
std::abort();
}
static bool g_uiServe = false; // --ui-serve: runMain runs once per script in one process
// One run of the app: the whole of main, also each script of the warm UI test server (--ui-serve, UiServe.cpp).
static int runMain(int argc, char** argv) {
sf::AppOptions options;
std::string logDir, crashTest;
bool sizeGiven = false;
sf::BenchCommandLine bench;
bool optimistic = false; // --bench-optimistic (research, docs/design/core-200m.md N1)
sf::OptimisticBenchOptions optimisticOptions;
bool calibrate = false, calibrateQuick = false, calibrateSave = true;
std::string studioProfile;
bool offline = false;
for (int i = 1; i < argc; ++i) {
std::string a = argv[i];
auto next = [&]() -> std::string { return i + 1 < argc ? argv[++i] : std::string(); };
if (sf::parseBenchArg(argc, argv, i, bench)) continue;
if (sf::parseOptimisticBenchArg(argc, argv, i, optimistic, optimisticOptions)) continue;
if (std::string(argv[i]) == "--bench-wavelet") { // research (docs/design/core-200m.md N2), CPU only
const std::string out = i + 1 < argc && argv[i + 1][0] != '-' ? argv[++i] : std::string();
return sf::runWaveletBench(out);
}
if (a == "--calibrate") calibrate = true;
else if (a == "--calibrate-quick") calibrate = calibrateQuick = true;
else if (a == "--calibrate-no-save") calibrateSave = false;
else if (a == "--run") options.script += next() + "\n";
else if (a == "--render") options.renderPath = next();
else if (a == "--turntable") options.turntable = std::atoi(next().c_str());
else if (a == "--size") sizeGiven = std::sscanf(next().c_str(), "%dx%d", &options.width, &options.height) == 2;
else if (a == "--view") std::sscanf(next().c_str(), "%f,%f", &options.yawDegrees, &options.pitchDegrees);
else if (a == "--zoom") options.zoom = std::max(0.05f, float(std::atof(next().c_str())));
else if (a == "--wireframe") options.wireframe = true;
else if (a == "--facegroups") options.facegroups = true;
else if (a == "--hide-mesh") options.hideMesh = true;
else if (a == "--demo") options.demo = next();
else if (a == "--record") options.recordPath = next();
else if (a == "--demo-asset") options.demoAsset = next();
else if (a == "--demo-output") options.demoOutput = next();
else if (a == "--fps") options.fps = std::atoi(next().c_str());
else if (a == "--supersample") options.supersample = std::clamp(std::atoi(next().c_str()), 1, 4);
else if (a == "--ui-test") options.uiTest = next();
else if (a == "--fullscreen") options.fullscreen = true;
else if (a == "--no-ai") sf::ai::setAiForcedOff(true); // as SF_AI=off (ai/AiPolicy.h)
else if (a == "--no-packs") sf::setPacksSafeMode(true); // safe mode: no installed pack is loaded
else if (a == "--studio") studioProfile = next(); // core/StudioProfile.h
else if (a == "--offline") offline = true;
else if (a == "--blender") options.blender = true;
else if (a == "--ui-out") options.uiOutDir = next();
else if (a == "--ui-record") options.uiRecordPath = next();
else if (a == "--log-dir") logDir = next();
else if (a == "--crash-test") crashTest = next();
else if (a == "--measure-idle") options.measureIdle = std::max(0.5f, float(std::atof(next().c_str())));
else if (a == "--measure-stroke") {
const std::string v = next(); // S or S,RADIUS
options.measureStroke = std::max(0.5f, float(std::atof(v.c_str())));
if (const size_t comma = v.find(','); comma != std::string::npos)
options.measureStrokeRadius = float(std::atof(v.c_str() + comma + 1));
}
else if (a == "--timelapse") options.timelapsePath = next();
else if (a == "--timelapse-seconds") options.timelapseSeconds = std::max(2.0f, float(std::atof(next().c_str())));
else if (a == "--benchmark") {
options.benchmark = true;
// An optional scene name: sculptforge --benchmark standard-15m
if (i + 1 < argc && (std::string(argv[i + 1]).rfind("standard", 0) == 0 || std::string(argv[i + 1]).rfind("core-", 0) == 0)) {
options.benchmarkScene = argv[++i];
if (options.benchmarkScene != "standard" && options.benchmarkScene != "standard-15m" &&
options.benchmarkScene != "standard-33m" && options.benchmarkScene != "standard-1b" &&
options.benchmarkScene != "core-200m" && options.benchmarkScene != "core-100m") {
std::fprintf(stderr, "Unknown benchmark scene %s (standard-15m, standard-33m, standard, standard-1b, core-100m or core-200m)\n", argv[i]);
return 1;
}
}
}
else if (a == "--focus-detail") options.openPath = next(); // a .sfdetail file (prototype)
else if (a == "--benchmark-file") { // a project from disk, the scoreboard's strokes (docs/design/perf-scoreboard.md)
options.benchmark = true;
options.benchmarkScene = "file:" + next();
}
else if (a == "--benchmark-script") { // a take in real time (BenchTake.cpp)
options.benchmark = true;
options.benchmarkScript = next();
}
else if (a == "--benchmark-sizes") options.benchmarkSizes = next();
else if (a == "--benchmark-out") options.benchmarkOut = next();
else if (a == "--benchmark-video") options.benchmarkVideo = next();
else if (a == "--benchmark-no-video") options.benchmarkNoVideo = true;
else if (a == "--benchmark-vsync") options.benchmarkVsync = true;
else if (a == "--benchmark-seconds") options.benchmarkStrokeSeconds = std::max(1.0f, float(std::atof(next().c_str())));
else if (a == "-h" || a == "--help") {
usage();
return 0;
} else if (!a.empty() && a[0] != '-') options.openPath = a;
else {
std::fprintf(stderr, "Unknown option %s\n", a.c_str());
usage();
return 1;
}
}
g_isolatedDir.clear(); // (the warm server's last script's folder)
if (automatedRun()) isolateSettings();
if (bench.run) return finishIsolated(sf::runAppBenchmark(bench));
if (optimistic) return finishIsolated(sf::runOptimisticBench(optimisticOptions));
if (calibrate) return finishIsolated(sf::runCalibrateCommandLine(calibrateQuick, calibrateSave));
if (!options.uiTest.empty()) {
if (!sizeGiven) options.width = 1600, options.height = 960;
isolateSettings();
}
if (options.benchmarkScene == "standard-1b") { // the asset first (written once, a few seconds), before any window
#if defined(_WIN32)
std::fprintf(stderr, "standard-1b (experimental Focus Detail) needs Linux or macOS for now\n");
return 1;
#endif
std::string error;
if (sf::focusStandard1bPath(error, [](const std::string& s) { std::fprintf(stderr, "%s\n", s.c_str()); }).empty()) {
std::fprintf(stderr, "standard-1b: %s\n", error.c_str());
return 1;
}
}
if (options.benchmarkScene == "core-200m" || options.benchmarkScene == "core-100m") { // research: micro triangles in memory, the project written once
std::string error;
if (sf::core200mScenePath(error, [](const std::string& s) { std::fprintf(stderr, "%s\n", s.c_str()); },
options.benchmarkScene == "core-100m" ? 100 : 200).empty()) {
std::fprintf(stderr, "%s: %s\n", options.benchmarkScene.c_str(), error.c_str());
return 1;
}
}
if (options.benchmark && !sizeGiven) options.width = 1920, options.height = 1080;
if (options.benchmark || !options.timelapsePath.empty()) isolateSettings(); // the user's settings and files untouched
if (!options.timelapsePath.empty() && !sizeGiven) options.width = 1920, options.height = 1080;
if (options.measureIdle > 0.0f || options.measureStroke > 0.0f) isolateSettings(); // a fresh start, no restore prompt, the user's files untouched
if (!options.recordPath.empty() && options.supersample > 1) { // the app renders large; the video keeps --size
options.width *= options.supersample;
options.height *= options.supersample;
}
sf::crashlog::start(logDir); // after isolateSettings: a UI test logs into its own folder
{ // studio mode: the network policy, brush shares and packs (after isolateSettings: tests install into their folder)
const char* base = SDL_GetBasePath();
const sf::StudioStart& studio = sf::startStudioMode(base ? base : "", studioProfile, offline);
sf::ai::setStudioAiAllowed(studio.profile.ai);
for (const std::string& m : studio.messages) SDL_Log("%s", m.c_str());
if (studio.active) SDL_Log("Studio mode%s: no outside connections", studio.profile.name.empty() ? "" : (" (" + studio.profile.name + ")").c_str());
}
if (!crashTest.empty()) crashOnPurpose(crashTest);
auto app = std::make_unique<sf::App>();
if (!app->init(options)) {
// A double-clicked app that can't start says why (#109: on a laptop it just vanished, not even in the
// Task Manager). Tests, renders and benchmarks keep failing quietly with their log.
const bool interactive = options.renderPath.empty() && options.recordPath.empty() && options.uiTest.empty() &&
options.timelapsePath.empty() && !options.benchmark && options.demo.empty() &&
!automatedRun();
if (interactive) {
std::string text = "SculptForge could not start.\n\n" +
(app->startError().empty() ? std::string("See the log for details.") : app->startError()) +
"\n\nUpdating the graphics driver (from the PC or GPU maker) usually fixes this.";
if (!sf::crashlog::path().empty()) text += "\n\nLog: " + sf::crashlog::path();
SDL_ShowSimpleMessageBox(SDL_MESSAGEBOX_ERROR, "SculptForge", text.c_str(), nullptr);
}
app->shutdown();
sf::crashlog::stop();
return 1;
}
const auto runStart = std::chrono::steady_clock::now();
int code = app->run();
const auto runEnd = std::chrono::steady_clock::now();
// Quitting always ends the process, even if a driver or thread stalls the teardown or the exit (core/ExitWatchdog.h).
// --ui-serve runs the next script in this process: never there.
if (!g_uiServe) sf::armExitWatchdog(15000, code);
app->shutdown();
app.reset();
if (std::getenv("SF_STARTUP_TIMES"))
std::fprintf(stderr, "run %.1f ms, shutdown %.1f ms\n", std::chrono::duration<double, std::milli>(runEnd - runStart).count(),
std::chrono::duration<double, std::milli>(std::chrono::steady_clock::now() - runEnd).count());
sf::crashlog::stop();
return finishIsolated(code);
}
#ifndef _WIN32
// --cli ARGS...: runs sculptforge-cli beside this program with ARGS. An AppImage has one entry point, so this is how an
// MCP client starts its server ("SculptForge.AppImage --cli --mcp", Help > Connect an AI tool). Only our own program.
static int execCli(int argc, char** argv) {
const char* base = SDL_GetBasePath();
const std::string cli = std::string(base ? base : "") + "sculptforge-cli";
std::vector<char*> args{const_cast<char*>(cli.c_str())};
for (int i = 2; i < argc; ++i) args.push_back(argv[i]);
args.push_back(nullptr);
execv(cli.c_str(), args.data());
std::fprintf(stderr, "sculptforge: couldn't start %s\n", cli.c_str());
return 127;
}
#endif
int main(int argc, char** argv) {
#ifndef _WIN32
if (argc >= 2 && std::string(argv[1]) == "--cli") return execCli(argc, argv);
#endif
if (argc >= 2 && std::string(argv[1]) == "--ui-serve") {
g_uiServe = true;
return sf::runUiServer(argc - 1, argv + 1, runMain);
}
return runMain(argc, argv);
}