ludusavi-manifest/README.md

Ludusavi Manifest

The Ludusavi Manifest format is a YAML structure for defining the location of game save data and other files that are of interest to back up. Although this project was started for use by Ludusavi, the goal is for the manifest format to be generic enough for any game backup tool to implement, while leaving room for new fields and functionality over time.

This repository contains the primary manifest, which is compiled from data on PCGamingWiki, along with accessing the Steam API for game installation directory names. If you find any data that is missing or incorrect, please contribute to the wiki, and such changes will be incorporated into the primary manifest periodically. There is also a list of games without any info on what to back up.

Game developers may include a secondary manifest (named .ludusavi.yaml) with their games, so that backup tools can automatically detect and use it to discover what files need to be backed up for save data and configuration.

Format

For the schema, refer to schema.yaml. Note that the primary manifest is validated with schema.strict.yaml, which additionally specifies enums for some fields. However, tools should implement schema.yaml, so that new values in the manifest do not break older tools.

Here is an example:

An Example Game:
  files:
    <base>/saves:
      tags:
        - save
    <base>/settings.json:
      when:
        - os: windows
        - os: linux
      tags:
        - config
    <base>/other:
      when:
        - os: mac
          store: steam
  installDir:
    AnExampleGame: {}
  registry:
    <regHkcu>/Software/An Example Game:
      tags:
        - save
        - config
  steamId: 123

This means:

• <base>/saves will be backed up on any system.
• <base>/settings.json will be backed up if you're using Windows or Linux.
• <base>/other will be backed up if you're using Mac and Steam.
• On Windows, the registry path <regHkcu>/Software/An Example Game will be backed up.

Paths can include these placeholders:

placeholder	meaning
<root>	a directory where games are installed (configured in backup tool)
<game>	an installDir (if defined) or the game's canonical name in the manifest
<base>	shorthand for <root>/**/<game>
<home>	current user's home directory in the OS (~)
<storeUserId>	current user's ID in the game store
<osUserName>	current user's name in the OS
<winAppData>	%APPDATA% on Windows
<winLocalAppData>	%LOCALAPPDATA% on Windows
<winPublic>	%PUBLIC% on Windows
<winProgramData>	%PROGRAMDATA% on Windows
<winDir>	%WINDIR% on Windows
<xdgData>	$XDG_DATA_HOME on Linux
<xdgConfig>	$XDG_CONFIG_HOME on Linux
regHkcu	HKEY_CURRENT_USER in the Windows registry
regHklm	HKEY_LOCAL_MACHINE in the Windows registry

Implementation

Tools must implement the following in addition to respecting the schema:

• For paths, first substitute the placeholders, then evaluate as a glob. Because of treating paths as globs, a path may match multiple files or directories.
• When a path identifies a folder, the backup includes all of its files and subdirectories recursively.
• Relative paths must be resolved relative to the location of the manifest file. This is important for secondary manifests to work correctly without hard-coding their location.
• If a tool supports secondary manifests, they must be automatically detected when they are named .ludusavi.yaml and exist anywhere within a configured root.

Tools may also:

• Use store-specific logic to narrow down the ** in <base>. For example, with Steam, it would be <root>/steamapps/common/<game>.

The latest version of the primary manifest can be downloaded from https://raw.githubusercontent.com/mtkennerly/ludusavi-manifest/master/data/manifest.yaml . To check for updates:

• Store the value of the ETag header for the last downloaded version.
• Send a GET request to the URL with the If-None-Match header set to the last known ETag value.
• If the response code is 304, then no update is needed.
• If the response code is 200, then store the new ETag value.

Development

Please refer to CONTRIBUTING.md.