Logo Ludusavi

Ludusavi is a tool for backing up your PC video game save data, written in Rust. It is cross-platform and supports multiple game stores.

Features

This tool uses the Ludusavi Manifest for info on what to back up, and it will automatically download the latest version of the primary manifest. The data is ultimately sourced from PCGamingWiki, so please contribute any new or fixed data back to the wiki itself, and your improvements will be incorporated into Ludusavi's data as well.

If you'd like to help translate Ludusavi into other languages, check out the Crowdin project.

Demo

GUI

GUI demo of previewing a backup

CLI

CLI demo of previewing a backup

Installation

Requirements

Methods

You can install Ludusavi one of these ways:

Notes

If you are on Windows:

If you are on Mac:

Usage

Roots

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. These are listed on the "other" screen, where you can use the plus button in the roots section to configure as many as you need, along with the root's type:

You may use [globs] in root paths to identify multiple roots at once. If you have a folder name that contains a special glob character, you can escape it by wrapping it in brackets (e.g., [ becomes [[]).

The order of the configured roots is not significant. The only case where it may make a difference is if Ludusavi finds secondary manifests (.ludusavi.yaml files) and those manfiests contain overlapping entries for the same game, in which case Ludusavi will merge the data together in the order that it finds them.

Backup retention

You can configure how many backups to keep by pressing the gear icon on the backup screen. A full backup contains all save data for a game, while a differential backup contains just the data that has changed since the last full backup.

When Ludusavi makes a new backup for a game, it will also remove any excess backups for that specific game. When a full backup is deleted, its associated differential backups are deleted as well.

For example, if you configure a retention limit of 2 full and 2 differential, then Ludusavi will create 2 differential backups for each full backup, like so:

When backup #7 is created, because the full retention is set to 2, Ludusavi will delete backups 1 through 3.

If your full retention is only 1 and your differential retention is 1+, then Ludusavi will keep the full backup and just delete the oldest differential as needed.

On the restore screen, you can use the three-dot menu next to a game to lock any of its backups. Locked backups do not count toward the retention limits and are retained indefinitely.

Cloud backup

Ludusavi integrates with Rclone to provide cloud backups. You can configure this on the "other" screen. Any Rclone remote is supported, but Ludusavi can help you configure some of the more common ones: Google Drive, OneDrive, Dropbox, Box, FTP servers, SMB servers, and WebDAV servers. Support is verified for Rclone 1.62.2, but other versions should work as well.

If you turn on automtic synchronization, then Ludusavi will check if your local and cloud saves are already in sync at the start of a backup. If so, then any changes will be uploaded once the backup is done. If they weren't in sync to begin with, then Ludusavi will warn you about the conflict and leave the cloud data alone. You can perform an upload or download at any time on the "other" screen to resolve such a conflict.

Bear in mind that many factors can affect cloud sync performance, including network speed, outages on the cloud side, and any limitations of Rclone itself. You can try setting custom Rclone arguments if you find that it is too slow. For example, --fast-list and/or --ignore-checksum can speed things up, while --transfers=1 can help to avoid rate-limiting but may slow things down. The "other" screen has a field to configure custom arguments, and you can find documentation for them here: https://rclone.org/flags

You can also use other cloud backup tools of your choice, as long as they can make the storage available as what looks like a normal folder. For example:

Selective scanning

Once you've done at least one full scan (via the preview/backup buttons), Ludusavi will remember the games it found and show them to you the next time you run the program. That way, you can selectively preview or back up a single game without doing a full scan. Use the three-dot menu next to each game's title to operate on just that one game.

You can also use keyboard shortcuts to swap the three-dot menu with some specific buttons:

Backup structure

During a restore, Ludusavi only considers folders with a mapping.yaml file.

Filter

You can click the filter icon at the top of the backup/restore screens to use some filters. Note that this only affects which games you see in the list, but Ludusavi will still back up the full set of games.

You can apply filters for the following:

Duplicates

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.

You can resolve conflicts by disabling certain save files from being backed up. Once a conflict is resolved, the badge will become faded. You can also click on the badge to view just the conflicting games.

Redirects

You can use redirects to back up or restore to a different location than the original file. These are listed on the "other" screen, where you can click the plus button to add more and then enter both the old location (source) and new location (target).

There are multiple types of redirects:

For example:

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

Custom games

You can create your own game save definitions on the custom games screen. If the game name exactly matches a known game, then your custom entry will override it.

For file 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. 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. If you have a folder name that contains a special glob character, you can escape it by wrapping it in brackets (e.g., [ becomes [[]).

Backup exclusions

Backup exclusions let you set paths and registry keys to completely ignore from all games. They will not be shown at all during backup scans.

Configure exclusions on the "other" screen.

For excluded file paths, you can use glob syntax. For example, to exclude all files named remotecache.vdf, you would specify **/remotecache.vdf.

Backup validation

On the restore screen, there is a "validate" button that will check the integrity of the latest backup (full + differential, if any) for each game. You won't normally need to use this, but it exists for troubleshooting purposes.

Specifically, this checks the following:

If it finds problems, then it will prompt you to create new full backups for the games in question. At this time, it will not remove the invalid backups, outside of your normal retention settings.

Command line

Run ludusavi --help for the CLI usage information. You can also view info for specific subcommands, such as ludusavi manifest update --help.

Configuration

Ludusavi stores its configuration in the following locations:

Alternatively, if you'd like Ludusavi to store its configuration in the same place as the executable, then simply create a file called ludusavi.portable in the directory that contains the executable file. You might want to do that if you're going to run Ludusavi from a flash drive on multiple computers.

If you're using the GUI, then it will automatically update the config file as needed, so you don't need to worry about its content. However, if you're using the CLI exclusively, then you'll need to edit config.yaml yourself.

Ludusavi also stores manifest.yaml (info on what to back up) here. You should not modify that file, because Ludusavi will overwrite your changes whenever it downloads a new copy.

Logging

Log files are stored in the config folder (see above). By default, only warnings and errors are logged, but you can customize this by setting the RUST_LOG environment variable (e.g., RUST_LOG=ludusavi=debug). The most recent 5 log files are kept, rotating on app launch or when a log reaches 10 MiB.

Interfaces

CLI API

CLI mode defaults to a human-readable format, but you can switch to a machine-readable JSON format with the --api flag.

Click to expand

For the backup/restore commands:

The backups command is similar, but without overall, and with each game containing {"backups": [ {"name": <string>, "when": <string>, "comment": <string>} ]}. The find command also does not have overall, and each game object is empty.

For the cloud upload and cloud download commands:

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.

API output goes on stdout, but stderr may still be used for human-readable warnings/errors. If stderr is not empty, you may want to log it, since not all human-readable warnings have an API equivalent.

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": {} } } }

Configuration file

Here are the available settings in config.yaml (all are required unless otherwise noted):

Click to expand

Example:

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

Environment variables

Environment variables can be used to tweak some additional behavior:

Click to expand

Comparison with other tools

There are other excellent backup tools available, but not a singular cross-platform and cross-store solution:

Troubleshooting

Development

Please refer to CONTRIBUTING.md.