Set up a project (mod folders, moving, session restore)

Project-level features the team added: reading a mod's files as read-only layers, moving a project folder, getting your session back after a restart, and names for Eclipse's characters.

Status: labels, file names and the layer order were read against the code. The inner steps of Move Project Folder (what happens on failure, across drives) come from its strings and summary comments, not a full read. Nothing was run.

Where saves land

Smithbox reads files through layers. The first layer that has a file wins:

1. the project folder,
2. the Additional Mod Folders, in the order listed,
3. the game data.

Map saves, Elden Ring asset copies and palette files are written to the project folder. The Additional Mod Folders are opened read-only. The Map Editor's save code writes through the project layer only, so the game install is not written to.

Smithbox's own per-project files live in <project>/.smithbox/. Those named on these pages:

Add an Additional Mod Folder

Use this so a mod's new characters, assets and maps show in the editors without copying them into the project. For Eclipse, that is the built mod folder.

1. Open the Projects window and select the project.
2. Open the Settings section.
3. Under Additional Mod Folders, type the folder path or press Browse, then press Add. The folder must be laid out like the game folder (chr/, asset/, map/, ...).
4. Optional: use the row buttons to move a folder up (earlier folders win) or remove it.
5. Press Update Project. For the loaded project this reloads it. The folders apply after the reload.

A listed folder that does not exist is shown in red with "(not found)" and is skipped with a log warning.

How to tell it worked: the mod's files show in the editors' lists, for example its characters on the Object Palette's Characters tab.

Move a project folder

Use this to pull a project out of a shared folder such as the desktop.

1. Open the Projects window, select the project and open Settings.
2. Under Project Directory, press Move Project Folder....
3. Pick the new folder. Pick an empty folder, or a folder that already holds files to get a new folder named after the project inside it.
4. Read the confirmation. It lists what moves and what stays. Confirm.

What moves: the game's own folders and files (chr, map, param, regulation.bin and so on) and Smithbox's .smithbox, .backup and project.json. Anything else in the old folder stays.

A loaded project is unloaded for the move and loaded again after. The project's Mod Engine 3 profile, if it has one, is pointed at the new folder. If the move fails the files are put back; a file open in another program (the game, a text editor) can block it. Across drives the files are copied and the originals then removed; any that could not be removed are listed.

How to tell it worked: a message says "The project now lives in:" with the new path.

Reopen where you left off

When a project loads, Smithbox brings back what was open when you last used it. It also does this after an update restart or a crash.

What is restored:

• the editor that was in front;
• the Map Editor's loaded maps (the one being edited loads first);
• the map selected in the Map List;
• the selection, up to 200 objects, by map and name;
• the camera position and rotation.

Block maps loaded as read-only context are left out; they come back by themselves with their tiles.

Where it is stored: %LOCALAPPDATA%\Smithbox\Sessions\<project guid>.json. It is kept outside the project so a shared project folder does not carry anyone's session. It is written a few seconds after anything changes, not on exit. The environment variable SMITHBOX_SESSION_DIR moves the folder (test copies use this).

To turn it off: Preferences, Project, General, Reopen Where You Left Off (setting Project_Restore_Session, on by default).

Unsaved edits are not restored. Only what was open is.

Eclipse character names

The Nightreign character alias list shipped with Smithbox (Assets/Aliases/NR/Characters.json) names 115 character models the Eclipse mod adds. Each carries the tag eclipse. They show wherever character names are shown, and you can search the Object Palette's Characters tab for eclipse.

To change one for your project only, use Edit community name... in the Object Palette (place-an-object.md). To change the shipped list, edit that JSON file in the Smithbox repo and rebuild (build-smithbox.md).

The characters themselves only show when the Eclipse mod folder is an Additional Mod Folder or its files are in the project.

What goes wrong

• A mod's files do not show. The project was not reloaded after adding the folder, or the path is the wrong level (it must contain chr/, map/ and so on directly).
• "The folder ... already has files in it. Pick an empty folder." Shown by Move Project Folder for a destination it cannot use.
• The session did not come back. The preference is off, the maps no longer exist in the project, or the restore waited more than five minutes for its maps.

Related

Before closing or rebuilding a running Smithbox, check for unsaved maps first. The session restore does not save edits.