8.1 KiB
Settings storage across the Craft apps
How every Craft app stores its settings, and what goes where. The shared code is
craft-settings; this page is the policy it implements.
Where the apps install on Windows, and what an update may move, is the companion policy
installation-policy.md.
Discussion: storytold/craft-libs#12.
What goes where
| Kind | Where | Why |
|---|---|---|
| Settings people might edit | config.toml in the config folder |
One readable file with comments, atomic saves, backup, recovery, migrations |
| Window and UI state | ui.ron / app.ron beside config.toml |
Changes every session; not worth comments or hand edits |
| Caches | Platform cache folder (paths::cache_dir); %LOCALAPPDATA% on Windows so it does not roam |
Disposable, large |
| Downloaded models | The user's chosen persistent model root (suggested %LOCALAPPDATA%\ArtCraft\models on Windows; $XDG_DATA_HOME/ArtCraft/models on Linux, or ~/.local/share/ArtCraft/models when it is unset) |
Persistent user assets: never deleted by cache cleanup or an app's uninstaller, never disposable (installation-policy.md) |
| Recovery and autosave files | Platform data folder (paths::data_dir) |
Not settings; must survive a settings reset |
| Settings that belong to a library or project (LightCraft) | Inside that folder, via SettingsStore::open_at |
Travels with the library |
| API keys and tokens | The OS keychain | Never in a plain-text file |
The config folder
First match wins. The store reports which rule applied, so apps can show the path in their about or settings screen.
- An override passed by the app, such as a
--config-dirflag <APP>_CONFIG_DIR, for examplePHOTOCRAFT_CONFIG_DIR(one per app, so redirecting one app does not move the others). Set but empty means isolated: nothing is read or written anywhere, the same as DesignCraft's existing behaviour, so tests and agents can never touch a user's real settings- Portable mode: a marker file next to the executable (next to the
.appon macOS, since writing inside a signed bundle breaks its signature). The default is a file namedportablewith settings inconfig/beside it; apps that already ship portable builds keep their own names (PhotoCraft:portable.txtorPhotoCraft.portable, folderPhotoCraftData) - The platform default:
Apps can also open a store with Location::Memory (for a switch like DESIGNCRAFT_NO_PREFS):
settings work in memory and nothing touches the disk.
| Platform | Folder |
|---|---|
| Linux / BSD | $XDG_CONFIG_HOME/<app>/, or ~/.config/<app>/ if unset |
| macOS | ~/Library/Application Support/<app>/ |
| Windows | %APPDATA%\<app>\ (Roaming) |
<app> is the app's lowercase id (photocraft, designcraft, …) on every platform, macOS
included (decided in #12). Existing Linux folder names do not change; the Launcher moves from
ai.storyteller.artcraft-launcher to artcraft-launcher.
If the folder cannot be created or written (a portable marker in /Applications, an AppImage
mount), the store opens read-only and says so at startup.
Files in the folder
config.toml: starts withschema_version = N, then one[section]per settings area. Written on first launch so people can find it.0600on Unix.config.toml.bak: the previous version, refreshed before every save.config.broken-<unix-ts>.toml: a file that was not valid TOML, moved aside and never deleted.
Saving and recovery
- Saves happen during use, half a second after the last change, atomically through
craft-atomic. A failed save leaves the old file intact and is retried with backoff; the app shows the error. - A file with a TOML syntax error is moved aside and defaults are used. A file that parses but
has a value that no longer fits (a renamed theme, a typo in a hand edit) is not treated as
broken: only that
[section]falls back to defaults and the app is told which one. - A file written by a newer build is shown but never overwritten.
- Comments, key order and keys the app does not know survive saves. If two instances of an app
are open, each re-reads the file before writing and merges in only its own changes, so the
other's survive. The app names how each item merges with
Settings::merge_rule: key by key (the default), whole (a window's place and size come from one instance), a recent list (what this instance opened or used again leads, cut to its limit) or a list of user entries (additions and removals from both are kept, an added entry stays after the entry before it). - Each save holds an advisory lock,
.config.toml.lockbeside the file, from re-reading the file to writing it, so two instances saving at the same moment take turns instead of one writing over the other's merge. A save waits at most 2 seconds for it, then saves anyway and logs a warning, so a stuck process never stops another from saving.
Migration
- Schema changes:
Settings::migrateupgrades the document one version at a time before it is parsed. A failed step leaves the file untouched and the store read-only. - Older per-app files (
prefs.json,ui.json,*.ron): imported on the first run that finds noconfig.toml, using the app's existing parser. The old file is left in place, so rolling back to an older build keeps working; apps can remove it a few releases later.
Where the apps are today
From the audit in #12 (Linux defaults, from source; overrides and portable mode change them). Before an app moves over, check where it saves on macOS and Windows so the importer finds the old files there too.
| App | Today | Moving to craft-settings |
|---|---|---|
| PhotoCraft | ~/.config/photocraft/preferences.json + eframe ui.ron; atomic saves with retries; portable via portable.txt/PhotoCraft.portable → PhotoCraftData/ |
Import preferences.json; keep ui.ron; keep its portable names via PORTABLE_MARKERS/PORTABLE_DIR |
| DesignCraft | ~/.config/designcraft/prefs.json + ui.json; saves on exit, ignores failures; empty DESIGNCRAFT_CONFIG_DIR and DESIGNCRAFT_NO_PREFS touch nothing |
Import prefs.json; keep ui.json; gain save-during-use and error reporting; DESIGNCRAFT_NO_PREFS → Location::Memory |
| EffectCraft | ~/.config/effectcraft/prefs.json, shortcuts.json, script_settings.json; atomic |
Import all three into sections of one config.toml |
| FilmCraft | ~/.local/share/filmcraft/preferences.json; atomic |
Import from the data folder; settings move to the config folder |
| GridCraft | ~/.config/gridcraft/prefs.json + ui.json; saves on exit, ignores failures |
Same as DesignCraft |
| LightCraft | global ui.json; library prefs.json, presets.json, view.json; atomic, backups, overwrite protection |
Global settings via open; library settings via open_at(library_dir) |
| VectorCraft | ~/.config/vectorcraft/ui.json with engine preferences inside; atomic, ignores failures |
Split engine preferences out into config.toml; keep UI state in ui.json |
| ArtCraft Launcher | ~/.local/share/ai.storyteller.artcraft-launcher/app.ron (eframe) |
Import from app.ron; needs its own tick timer while in the tray |
Adoption order: PhotoCraft and DesignCraft first (closest to and furthest from the target behaviour), then the rest.
Settings on the web
A browser build (wasm32) opens the same SettingsStore. Its files are localStorage items
(LocalStorageFiles, the default there), keyed by path, so Location::Dir(dir) names the key
prefix; Location::Auto keeps settings in memory. Storage holds about 5 MB per site, so the
store caps an item at 4 MB: a stored item over the cap reads as absent and the next save replaces
it, and a save over the cap fails and keeps the old item. An app's older hand-written item is a
LegacyFile read through the same storage. Browser storage takes no lock; tabs of one site share
the items, and each save still merges in what another tab wrote since.
Not yet
- Reloading settings when the file changes on disk while the app runs
- Removing imported legacy files