Ludusavi

• This is the default mode when you open the program.

• You can press preview to see what the backup will include, without actually performing it.

  If you do a preview, then Ludusavi will use that list of games for the next backup, so that the next backup doesn't have to do another full scan. It will also remember these games the next time you open the program so that you can selectively preview just a few of them, if you like, before or instead of running a full scan.

• The gear icon will reveal some additional options:

  • You can set a number of full and differential backups to keep. For example, if you set 2 full and 2 differential, then the first backup for a game will be a full, and then the next two backups will be differential. That repeats for the next three backups. When a third full backup is made, the first full backup and its two associated differentials are deleted.
  • You can enable compressed zip backups instead of plain files/folders.

• You can press back up to perform the backup for real.

  • If you've disabled the merge option, then the target folder will be deleted first if it exists, then recreated.
  • Within the target folder, for every game with data to back up, a subfolder will be created based on the game's name, where some invalid characters are replaced by _. In rare cases, if the whole name is invalid characters, then it will be renamed to ludusavi-renamed-<ENCODED_NAME>.
  • Within each game's subfolder, there will be a mapping.yaml file that Ludusavi needs to identify the game.

  When using the simple backup format, there will be some drive folders (e.g., drive-C on Windows or drive-0 on Linux and Mac) containing the backup files, matching the normal file locations on your computer. When using the zip backup format, there will be zip files instead.

  • If the game has save data in the registry and you are using Windows, then the game's subfolder will also contain a registry.yaml file (or it will be placed in each backup's zip file). If you are using Steam and Proton instead of Windows, then the Proton *.reg files will be backed up along with the other game files instead.

• Roots are folders that Ludusavi can check for additional game data. When you first run Ludusavi, it will try to find some common roots on your system, but you may end up without any configured. You can click add root to configure as many as you need, along with the root's type:

  • For a Steam root, this should be the folder containing the steamapps and userdata subdirectories. Here are some common/standard locations:
  • Windows: C:/Program Files (x86)/Steam
  • Linux: ~/.steam/steam
  • For the "other" root type and the remaining store-specific roots, this should be a folder whose direct children are individual games. For example, in the Epic Games store, this would be what you choose as the "install location" for your games (e.g., if you choose D:/Epic and it creates a subfolder for D:/Epic/Celeste, then the root would be D:/Epic).
  • For a home folder root, you may specify any folder. Whenever Ludusavi normally checks your standard home folder (Windows: %USERPROFILE%, Linux/Mac: ~), it will additionally check this root. This is useful if you set a custom HOME to manipulate the location of save data.
  • For a Wine prefix root, this should be the folder containing drive_c. Currently, Ludusavi does not back up registry-based saves from the prefix, but will back up any file-based saves.

  You may use globs in root paths to identify multiple roots at once.

• To select/deselect specific games, you can run a preview, then click the checkboxes by each game. You can also press the deselect all button (when all games are selected) or the select all button (when at least one game is deselected) to quickly toggle all of them at once. Ludusavi will remember your most recent checkbox settings.

• Next to each game's name is a menu with actions to perform on it. You can also use keyboard shortcuts to replace the menu with some specific action shortcuts:

  • preview: shift
  • backup/restore: ctrl (Mac: cmd)
  • backup/restore without confirmation: ctrl + alt (Mac: cmd + option)
• You can click the search icon and enter some text to just see games with matching names. Note that this only affects which games you see in the list, but Ludusavi will still back up the full set of games. This also provides some sorting options.
• You may see a "duplicates" badge next to some games. This means that some of the same files were also backed up for another game. That could be intentional (e.g., an HD remaster may reuse the original save locations), but it could also be a sign of an issue in the manifest data. You can expand the game's file list to see which exact entries are duplicated.

• Switch to restore mode by clicking the restore mode button.
• You can press preview to see what the restore will include, without actually performing it.
• You can press restore to perform the restore for real.
  • For each subfolder in the source directory, Ludusavi looks for a mapping.yaml file in order to identify each game. Subfolders without that file, or with an invalid one, are ignored.
  • All files from the drive folders (or zips) are copied back to their original locations on the respective drive. Any necessary parent directories will be created as well before the copy, but if the directories already exist, then their current files will be left alone (other than overwriting the ones that are being restored from the backup).
  • If the backup includes a registry.yaml file, then the Windows registry data will be restored as well.

• You can use redirects to restore to a different location than the original file. Click add redirect, and then enter both the old and new location. For example, if you backed up some saves from C:/Games, but then you moved it to D:/Games, then you would put C:/Games as the source and D:/Games as the target.

  Tip: As you're editing your redirects, try running a preview and expanding some games' file lists. This will show you in real time what effect your redirects will have when you perform the restore for real.

• You can select/deselect specific games in restore mode just like you can in backup mode. The checkbox settings are remembered separately for both modes.
• You can click the search icon and enter some text to just see games with matching names. Note that this only affects which games you see in the list, but Ludusavi will still restore the full set of games.

• Switch to this mode by clicking the custom games button.
• You can click add game to add entries for as many games as you like. Within each game's entry, you can click the plus icons to add paths (files or directories) and registry keys.
  • For paths, you can click the browse button to quickly select a folder. The path can be a file too, but the browse button only lets you choose folders at this time. You can just type in the file name afterwards.
  • In addition to regular paths, you can also use globs (e.g., C:/example/*.txt selects all TXT files in that folder) and the placeholders defined in the Ludusavi Manifest format.

• Make sure to give the game entry a name. Entries without names are ignored, as are empty paths and empty registry keys.

  If the game name matches one from Ludusavi's primary data set, then your custom entry will override it. This can be used to totally ignore a game (just don't specify any paths or registry) or to customize what is included in the backup.

CLI mode defaults to a human-readable format, but you can switch to a machine-readable JSON format with the --api flag. In that case, the output will have the following structure for the backup/restore commands:

• errors (optional, map):
  • someGamesFailed (optional, boolean): Whether any games failed.
  • unknownGames (optional, list of strings): Names of unknown games, if any.
• overall (map):
  • totalGames (number): How many games were found.
  • totalBytes (number): How many bytes are used by files associated with found games.
  • processedGames (number): How many games were processed. This excludes ignored, failed, and cancelled games.
  • processedBytes (number): How many bytes were processed. This excludes ignored, failed, and cancelled games.

• games (map):

  • Each key is the name of a game, and the value is a map with these fields:

  • decision (string): How Ludusavi decided to handle this game.

    Possible values:

    • Processed
    • Ignored
    • Cancelled
  • files (map):
    • Each key is a file path, and each value is a map with these fields:
    • failed (optional, boolean): Whether this entry failed to process.
    • ignored (optional, boolean): Whether this entry was ignored.
    • bytes (number): Size of the file.
    • originalPath (optional, string): If the file was restored to a redirected location, then this is its original path.
    • duplicatedBy (optional, array of strings): Any other games that also have the same file path.
  • registry (map):
    • Each key is a registry path, and each value is a map with these fields:
    • failed (optional, boolean): Whether this entry failed to process.
    • ignored (optional, boolean): Whether this entry was ignored.
    • duplicatedBy (optional, array of strings): Any other games that also have the same registry path.

The backups command is similar, but without overall, and with each game containing {"backups": [ {"name": <string>, "when": <string>} ]}

Note that, in some error conditions, there may not be any JSON output, so you should check if stdout was blank before trying to parse it. If the command line input cannot be parsed, then the output will not be in a stable format.

Example:

json { "errors": { "someGamesFailed": true, }, "overall": { "totalGames": 2, "totalBytes": 150, "processedGames": 1, "processedBytes": 100, }, "games": { "Game 1": { "decision": "Processed", "files": { "/games/game1/save.json": { "bytes": 100 } }, "registry": { "HKEY_CURRENT_USER/Software/Game1": { "failed": true } } }, "Game 2": { "decision": "Ignored", "files": { "/games/game2/save.json": { "bytes": 50 } }, "registry": {} } } }

• manifest (map):
  • url (string): Where to download the primary manifest.
  • etag (string or null): An identifier for the current version of the manifest. This is generated automatically when the manifest is updated.

• language (string, optional): Display language. Valid options: en-US (English, default), fil-PH (Filipino), de-DE (German), it-IT (Italian), pt-BR (Brazilian Portuguese), pl-PL (Polish), es-ES (Spanish).

  Experimental options that currently have graphical display issues: ar-SA (Arabic), zh-Hans (Simplified Chinese).

• theme (string, optional): Visual theme. Valid options: light (default), dark.
• roots (list):
  • Each entry in the list should be a map with these fields:
  • path (string): Where the root is located on your system.
  • store (string): Game store associated with the root. Valid options: epic, gog, gogGalaxy, microsoft, origin, prime, steam, uplay, otherHome, otherWine, other
• backup (map):
  • path (string): Full path to a directory in which to save backups. This can be overridden in the CLI with --path.
  • ignoredGames (optional, array of strings): Names of games to skip when backing up. This can be overridden in the CLI by passing a list of games.
  • merge (optional, boolean): Whether to merge save data into the target directory rather than deleting the directory first. Default: true.
  • filter (optional, map):
  • excludeOtherOsData (optional, boolean): If true, then the backup should exclude any files that have only been confirmed for a different operating system than the one you're using. On Linux, Proton saves will still be backed up regardless of this setting. Default: false.
  • excludeStoreScreenshots (optional, boolean): If true, then the backup should exclude screenshots from stores like Steam. Default: false.
  • ignoredPaths (list of strings): Globally ignored paths.
  • ignoredRegistry (list of strings): Globally ignored registry keys.
  • toggledPaths (map): Paths overridden for inclusion/exclusion in the backup. Each key is a game name, and the value is another map. In the inner map, each key is a path, and the value is a boolean (true = included). Settings on child paths override settings on parent paths.
  • toggledRegistry (map): Same as toggledPaths, but for registry entries.
  • sort (map):
  • key (string): One of name, size.
  • reversed (boolean): If true, sort reverse alphabetical or from the largest size.
  • retention (map):
  • full (integer): Full backups to keep. Range: 1-255.
  • differential (integer): Full backups to keep. Range: 0-255.
  • format (map):
  • chosen (string): One of simple, zip.
  • zip (map): Settings for the zip format.
    • compression (string): One of none, deflate, bzip2, zstd.
• restore (map):
  • path (string): Full path to a directory from which to restore data. This can be overridden in the CLI with --path.
  • ignoredGames (optional, list of strings): Names of games to skip when restoring. This can be overridden in the CLI by passing a list of games.
  • redirects (optional, list):
  • Each entry in the list should be a map with these fields:
    • source (string): The original location when the backup was performed.
    • target (string): The new location.
  • sort (map):
  • key (string): One of name, size.
  • reversed (boolean): If true, sort reverse alphabetical or from the largest size.
• customGames (optional, list):
  • Each entry in the list should be a map with these fields:
  • name (string): Name of the game.
  • files (optional, list of strings): Any files or directories you want to back up.
  • registry (optional, list of strings): Any registry keys you want to back up.

Example:

yaml manifest: url: "https://raw.githubusercontent.com/mtkennerly/ludusavi-manifest/master/data/manifest.yaml" etag: null roots: - path: "D:/Steam" store: steam backup: path: ~/ludusavi-backup restore: path: ~/ludusavi-backup