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

  1. Wait for the Map Editor's sync indicator to finish. Cloud sync is helpful but is not a backup of every local file.
  2. Close every smudgy window so logs, settings, package state, and map files are no longer being written.
  3. Copy the entire smudgy directory to a dated location.
  4. 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:

  1. reads and validates the old document;
  2. writes an untouched, timestamped copy under local/areas-v1-backup/;
  3. converts the map in memory; and
  4. 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.