Table of Contents
Data files and backups
Smudgy keeps ordinary configuration under your Documents directory:
Documents/smudgy/
Development builds use Documents/smudgy-dev/ so test accounts, servers, maps, and packages do not alter release data. Release candidates use the release directory.
Make a complete backup
- Wait for the Map Editor's sync indicator to finish. Cloud sync is helpful but is not a backup of every local file.
- Close every smudgy window so logs, settings, package state, and map files are no longer being written.
- Copy the entire
smudgydirectory to a dated location. - Keep at least one backup outside the computer when the maps or scripts would be difficult to recreate.
The operating-system credential store is separate. A directory backup does not necessarily include saved profile passwords, account sessions, API keys, or package secrets. Plan to sign in again and re-enter secrets after moving to another computer. When no credential store is available, some secrets use obfuscated fallback files inside the data directory. Those files are copied by a backup and are not encrypted, so protect the backup as you would protect the credentials themselves.
What is in the top-level directory
| Path | Purpose |
|---|---|
settings.json | Global appearance, input, logging, map preferences, and update settings. |
map-scopes.json | Which cloud map folders and loose areas belong to which server entries. |
maps/ | The local cache of cloud maps. Pending writes make this worth preserving even though the server is authoritative after sync. |
smudgy.log | Application diagnostics, not MUD session output. |
<server>/ | One directory for each saved server. |
Account metadata may also appear here, while secret tokens normally live in the system keyring.
What is in a server directory
| Path | Purpose |
|---|---|
server.json | Host, port, TLS, compression, and encoding. |
profiles/<profile>/profile.json | Profile name, description, and commands sent on connect. The protected password value is not stored here. |
aliases/aliases.json | Saved aliases, plus optional file-based alias scripts. |
triggers/triggers.json | Saved triggers, plus optional file-based trigger scripts. |
hotkeys/hotkeys.json | Saved hotkeys, plus optional file-based hotkey scripts. |
packages.json | Folder organization and enabled state for saved automations. |
modules/ | Personal JavaScript and TypeScript modules. |
packages/ | Local package source you own or are developing. |
smudgy.lock.json | Installed package roots, versions, integrity records, consent, trust, and enabled state. |
smudgy.params.json | Non-secret values entered for installed package parameters. |
local/ | Authoritative maps stored only for this server, including promoted session maps. |
logs/ | Readable and optional raw session logs. |
.isolate-storage/ | Persistent private data for sandboxed installed packages. |
Other generated caches and TypeScript support files can be recreated, but copying the whole server directory avoids deciding under pressure which ones matter.
Local map versions and migration backups
Local maps use a versioned document format. Current authoritative files are stored below:
<server>/local/areas-v2/
When Smudgy first encounters a map from the previous format under local/areas/, it:
- reads and validates the old document;
- writes an untouched, timestamped copy under
local/areas-v1-backup/; - converts the map in memory; and
- writes the converted document atomically under
local/areas-v2/.
The original areas/ file is not rewritten. If validation, backup creation, conversion, or the final write fails, the old file remains the source Smudgy can retry from. A file from a newer format is left unchanged and reported as requiring a newer client; Smudgy does not attempt to downgrade it.
These migration copies protect the map-format transition, but they are not a substitute for a backup of the complete Smudgy directory. Keep the folders together: copying one JSON document without its surrounding map set can break cross-area relationships.
Restore conservatively
Close smudgy first. Preserve the current directory under another name, then restore a complete backup rather than mixing arbitrary versions of interdependent JSON files. If only one script is bad, restore that file and its definition together.
Cloud maps may reconcile after sign-in. Local maps under each server's local/ directory do not come from the cloud and must be restored from backup. Restore the complete local/ directory, including its versioned area and migration-backup folders, rather than mixing documents from different snapshots.
Before manual edits
The UI validates identifiers, patterns, manifests, and relationships. A text editor does not. Keep the untouched backup, use a JSON-aware editor, and change one thing at a time. A malformed file may be treated as unreadable or cause the corresponding server, profile, or automation set to be skipped.