solidcraft/docs/book/src/guide/files.md

Import and export

Format	Read	Write
.solidcraft (versioned container or JSON design)	yes	yes
.json (self-contained plain JSON design)	yes	yes
STEP (AP203, AP214, AP242)	solids, assemblies, units, names, colours	AP242 with names, colours and the component tree
IGES 5.3	manifold solids, or trimmed surfaces sewn into solids	manifold solids with names and colours
FreeCAD .FCStd, Rhino .3dm	solids, through cadmpeg
3MF, STL, OBJ	mesh bodies	yes
glTF 2.0 (.glb, .gltf with its .bin files)	mesh bodies in the node tree's components, materials as appearances
3MF with face tags	as 3MF	each triangle tagged with its B-rep face, exact coordinates
URDF		the assembly as a robot: links with meshes, mass and inertia, joints from the assembly's joints
DXF, SVG	into a sketch	sketches and flat patterns as DXF
PNG, JPEG	canvases and decals

Opening a STEP, IGES, FreeCAD or Rhino file creates a design with the file's bodies as a base feature, and inserting one adds them to the current design. Later features build on them. Mesh bodies render, measure, move and export, but solid features need B-rep bodies.

Every imported file (STEP, IGES, 3MF, STL, OBJ or glTF) comes in as a new component named after the file, so its bodies never mix with yours. A STEP assembly keeps its structure: its parts and sub-assemblies become nested components, and a part used several times is one component with an occurrence for each place. The imported assembly is rigid: moving its component moves everything, and its parts don't move on their own. Right-click the component and choose Unlock Contents to joint the parts one by one. Undo removes a whole import in one step.

A glTF file (.glb, or .gltf with the .bin files it names in the same folder) comes in the same way: its nodes become nested components, a mesh placed several times is one component with an occurrence for each place, and the whole import is rigid until you unlock it. glTF is in metres with Y up, so the import is scaled to millimetres and turned to stand Z up (up: "z" keeps the file's axes). Each material's base colour, metal and roughness become the body's appearance, so the model looks right in Render; textures, skins and animations are not imported. Scaled or mirrored nodes are baked into their meshes. Compressed meshes (Draco, meshopt) are refused with a message: save the file uncompressed first.

A 3MF project saved by a slicer comes in too, also when it keeps its objects in model parts of their own inside the file (the 3MF Production extension): each object on the build plates becomes one mesh body, with all its volumes merged where the slicer placed them. Each body is named after its object: the name in the model, else the one the slicer keeps in its project settings (Bambu Studio's Metadata/model_settings.config), else Mesh1, Mesh2, … Other slicer-only data (modifier, negative and support volumes, painting, per-object settings) is not read: modifier and negative volumes come in as ordinary solid geometry.

File → Export STL… and File → Export 3MF… (also Save As Mesh on the Insert tab's Files panel, and in the right-click menu of a body) open the same dialog with that format chosen; it saves the selected bodies as STL, 3MF or 3MF with face tags (below) to a file you name, and you can change the format there.

File → Send to Slicer (also on the Insert tab's Files panel, and in the right-click menu of a body) is the short way: it saves the selected bodies as a 3MF in millimetres, without face tags, and sends it to a slicer. It always asks which one and pre-selects the slicer you used last time, so the usual case is one click or Enter. The list shows the slicers found on the computer with their icons; Custom… adds any other program to the top of the list (kept between runs; hover an entry you added and press Delete to remove it). On Linux only, a program whose desktop entry says it opens 3MF or STL files is listed even if SolidCraft doesn't know it by name. Windows and macOS list the known slicers only, found in the usual program folders and on PATH. It falls back to an STL if the 3MF can't be written. Scripts and the control channel use file.send_to_slicer with a slicer, which sends without a dialog. They can start only the slicers in the list and programs you added under Custom…; any other program path is refused, and an AI agent's request to save a mesh or send it to a slicer asks first and names the slicer.

The list also has a plain EasyPrint (Printables, in the browser) row, and it is the one entry that works in the browser build too. EasyPrint is Printables' slicer, so choosing it uploads the selected bodies (a 3MF, 100 MB at most) to Printables' servers and opens the model there in your browser. The link expires after 30 minutes, and you need to be signed in to Printables. SolidCraft asks once before the first upload and remembers that you agreed. Nothing is uploaded unless you pick this row. SolidCraft isn't affiliated with Printables. Scripts use file.open_in_easyprint, which refuses unless it gets consent: true, and an AI agent's request to use it asks first.

Files sent to a slicer go to a folder only you can read: ~/.cache/solidcraft/slicer on Linux, ~/Library/Caches/SolidCraft/slicer on macOS and %LOCALAPPDATA%\SolidCraft\slicer on Windows. The name stays the same for the same design and the same bodies, so sending again replaces the file the slicer has open: use the slicer's Reload from disk to pick it up. If Windows won't let the file be replaced because the slicer holds it, the new copy gets a number (name-2.3mf) and the status line says so. Files older than seven days are deleted the next time SolidCraft starts.

If the slicer is already running, PrusaSlicer, SuperSlicer and Cura load the file in the open window instead of starting another one (they are started with --single-instance). Other slicers, Bambu Studio and OrcaSlicer among them, are started as they are, so they may open a second window. You can turn this off in Preferences → General, except for PrusaSlicer 3.0, whose launcher can't hand a file to a running window without it. Scripts pass single_instance: false to file.send_to_slicer or file.save_mesh.

PrusaSlicer 2 and 3 behave differently, so SolidCraft reads which one an install is from the version in its installed metadata (a Flatpak's own files, or the metainfo file of a package); it never runs the program to ask. PrusaSlicer 2 is sent the file with --single-instance. PrusaSlicer 3 is started on its own first, SolidCraft waits up to ten seconds for it to be ready, and then sends the file. If the version can't be read, the command decides: the slic3r-app-launcher launcher is treated as PrusaSlicer 3, and any other entry is left as it is.

Closed mechanical meshes with a constant cross-section can be rebuilt as solids with the mesh.convert command (command palette, scripts and the control channel).

File → Export 3MF… with the format changed to 3MF with face tags (file.export or file.save_mesh with format: "3mf-tagged") writes an ordinary 3MF in which every triangle also names the B-rep face it lies on and every coordinate is the tessellation's own double-precision value. Meshing and analysis tools can use the tags to keep a model's faces (for loads, boundary conditions or feature edges); other 3MF readers ignore them. The format is specified in docs/formats/3mf-face-tags.md.

File → Export URDF… (file.export with a .urdf path) writes the assembly for robot simulators and ROS: a link per component placement with its mesh, mass and inertia, and the assembly's joints, so the parts move in the simulator as they do in SolidCraft. The meshes are written as STL files next to the .urdf. See docs/urdf.md.

Saves are atomic: a crash at any moment leaves either the old file or the new one, and the replaced version is kept as <file>.bak. A save keeps the file's permissions, and a design opened through a symbolic link (a synced folder linked into a project) is saved into the file the link points to, so the link stays. Unsaved changes in every open tab are autosaved to separate entries in a recovery folder, and the next launch offers to recover each design. Saving or closing one tab removes only its recovery entry. Older design files are upgraded on open, and files from a newer version are refused with a message.

Save writes a container by default; files named .json keep JSON on subsequent saves. Save As offers a container or plain JSON on desktop; Save As JSON is also available in the File menu on desktop and web. Choose the .json extension for plain JSON. Export Design as JSON writes an independent, self-contained copy without changing the current file. Scripts can explicitly pass "format": "json" to file.save or file.save_as even with a .solidcraft name. Opening detects the format from the contents, so existing JSON designs keep working. Containers favor fast reading and saving by default. Scripts can request "compression": "compact" when file size matters more than CPU time.

Containers deduplicate identical STEP, mesh and image payloads. Mesh coordinates retain their original double precision; this is not a conversion to STL. Geometry still rebuilds from the timeline when opening. When a saved display preview is available, desktop Open shows it while checking geometry; editing starts after the complete rebuild. Cancelling keeps the current design. Previews cannot be edited or measured. Scripts can opt in to a disposable geometry cache with cache: true on warm saves; saving never rebuilds cold geometry just to create one. Ordinary saves and browser downloads default to cache: false. An additional display-mesh cache remains opt-in with preview: true. Unsupported or mismatched caches are ignored. Browser opening still rebuilds synchronously. Warm saves with explicit cache: true can also include a small PNG thumbnail. It travels with the file, so Home can show the recent design without reconstructing it when no local picture is available. Missing or incompatible pictures use the usual thumbnail generation. The default cache: false omits the portable thumbnail too. The repository's docs/design-container.md describes limits and encoding details.

Designs are saved in the newest format this version of SolidCraft knows ("format": "solidcraft/N" in the file). It opens designs of every older format and upgrades them as they open; a design from a newer version asks you to update instead of being guessed at. Development (nightly) builds save a format number no release reads yet.

Sketch patterns retain their live direction-line references and placement settings when saved. Older patterns keep their fixed vector directions and original placement defaults.

Upgrading keeps what a design meant. Designs keep recorded body transfers, explicit 3D curve coordinate spaces and certified face bindings, alongside semantic configuration styles, associative free-form offsets and cylindrical emboss selections. Older ownership maps, geometry and expressions retain their saved meaning. Legacy 3D curves with retained associations receive their producer's coordinate-space marker without changing any saved points; detached curves retain world coordinates. A lost cross-component association refreshed by an older build may need an explicit relink or refresh when its source returns. Loading never guesses a numerical correction. Association records, coordinate arrays and placements are bounded and checked.

Design properties

File → Design Properties… (also under Document Settings in the Browser, and on the top component's right-click menu) records who made a design and what it is: project, part number, revision, author, organization, description and licence. OK applies the changes as one undo step. Scripts and agents use the same commands: document.metadata reads them, document.metadata.set (key and value, or values: {key: value, …}) and document.metadata.remove (key or keys) change them. document.inspect and the MCP inspect_design tool include them.

Exports carry them where the format has a place for them:

Format	Written
STEP	author and organization in FILE_NAME, description in FILE_DESCRIPTION (on one line)
IGES	author and organization in the global section
3MF	project as Title, author as Designer, description as Description, license as LicenseTerms

The part number and revision have no standard place in these formats and stay in the design.

In the file they are one optional top-level metadata object; a design without properties has none, and is saved exactly as before:

"metadata": {
  "project": "ACME enclosures",
  "part_number": "ACME-1042",
  "revision": "B",
  "author": "Jane Doe",
  "organization": "ACME",
  "description": "Vented case for Raspberry Pi 4",
  "license": "CC-BY-4.0",
  "com.acme.description": { "shop_id": 88123 },
  "org.printfarm": { "slicer_profile": "PETG-0.2", "internal_id": 4 }
}

• SolidCraft's keys are unprefixed and hold text. Every other unprefixed key is reserved for later SolidCraft versions.
• Other tools keep their data under one reverse-DNS key of their own (com.example.tool: two or more dot-separated labels of letters, digits, - and _), holding an object. A tool writes only under its own key and leaves the others alone.
• SolidCraft keeps every key as it is through open, edit and save, in both the container and plain JSON, and never checks what another tool wrote: a well-known key holding something other than text ("author": 42) is kept, reads as absent, and never stops the design from opening. Typing over it in Design Properties replaces it.
• Other tools' keys are never exported; Design Properties lists them read-only.
• Keep values small: document.metadata.set refuses text over 4 KiB, an object over 64 KiB or nested more than 32 levels deep, and more than 256 keys or 256 KiB in all. Binary data belongs in a file next to the design.

Design properties are first saved in format 21. Inserting or linking another design doesn't copy its properties; Save As keeps them. A command script of the design (timeline.export_script) sets them in one step.

Designs in shared or synced folders

A design kept on a network share or in a synced folder (Dropbox, OneDrive, Syncthing, Google Drive) can be open on two computers at once. The desktop app watches for two writers:

• Open elsewhere. While a design is open, SolidCraft keeps a small lock file next to it, .~<file>.lock (computer, user, SolidCraft version, when it was opened), refreshes it every minute and removes it when the design closes. Opening a design that another SolidCraft has open says so: Open Read-Only (look at it; Save asks for a new file), Open Anyway or Cancel. A lock not refreshed for three minutes (left by a crash or a lost connection) is ignored. Lock files never show in Open or the recent lists, and a design in a folder you can't write to still opens.
• Changed on disk. SolidCraft remembers the file's size and modification time when it opens or saves a design. If another program or computer wrote the file since, Save asks first: Save a Copy (the default), Overwrite or Cancel.

Scripts, the CLI and the control channel never get these questions. doc.open opens the design and reports open_elsewhere in its result (read_only: true opens it read-only), and file.save over a file that changed on disk fails with an error until it is given overwrite: true.

Saving in the web app

In Chrome, Edge and Opera, Save As opens your browser's save dialog and writes the .solidcraft file to the folder you choose, and Open opens the browser's open dialog. Save then writes back to that same file. The browser remembers the file, so after you reload the page the first Save asks once for permission to write to it, and carries on. A design you open from your computer saves back to the file you opened.

In Firefox and Safari, which can't write to a folder, Save and Save As keep designs in this browser's private storage instead, and the app says so. Clearing the site's data can remove those designs. Download a copy to keep it outside the browser or move it to another device.

To get a copy as a download in any browser, choose File → Download design. It holds the current design, including its unsaved changes. In File → Files in this browser… (and in Firefox and Safari, File → Open), Download open design does the same, and Download beside a stored file gives its last saved contents. Whether a folder chooser appears depends on your browser's download settings.

Use Open from computer… in the same window to open a design from your computer; where the browser can write to a folder it saves back to that file, otherwise it works on a copy kept in the browser. Use Rename beside a stored file to change its name. Autosave and recovery stay in the browser's private storage in every browser. Exports such as STEP and STL are downloaded.