Unaffiliated

Home Documentation & Help
Steamworks Documentation
Steam Cloud

Steam Cloud Overview

The Steam Cloud provides an easy and transparent remote file storage system for your game. Files specified in the Auto-Cloud configuration or written to disk (created, modified, deleted, etc.) using the Cloud API will automatically be replicated to the Steam servers after the game exits.

If the user changes computers, the files are automatically downloaded to the new computer prior to the game launching. The game can then access the files by reading them through the Cloud API or reading them directly from disk as usual. Avoid machine specific configurations such as video settings.

The Steam Client does the work of ensuring that the files are kept synchronized across all computers the user may be accessing.

Users can globally disable Cloud synchronization in the Steam Settings under Cloud by unchecking "Enable Steam Cloud synchronization for applications which support it."

Users can also disable the Cloud synchronization on a per game basis in each games properties.

Spacewar_Cloud_Properties.png

Initial Setup

To set up Steam Cloud you must set the Byte quota per user and Number of files allowed per user options on the Steam Cloud Settings page in the Steamworks App Admin panel.

This quota is enforced on each Cloud-enabled game, on a per-user-per-game basis. It's recommended to set the values to reasonable amounts for your game title.

NOTE: Don't forget to click Save at the bottom of the page, and Publish your updated settings. Once published the cloud icon will be visible in the Steam client for anyone that owns your game.

If your game has already been released to the public then you can check the box labeled Enable cloud support for developers only. If developers-only mode is enabled then only the steam accounts which own a "Developer Comp" license for your title will see the cloud icon and will be able to use the Steam Cloud. This is useful to safely test Steam Cloud integration without breaking the public user experience. This has no effect on unreleased games since no one owns the game yet, they won't be able to see or access any cloud storage for the specific app ID.

You are able to share Cloud storage space between two app IDs by filling out the Shared cloud APP ID field. This is most commonly used to share saved games between a demo and a full game. A value of 0 disables this feature.

Steam Cloud API and Steam Auto-Cloud

Steam provides two different methods of utilizing the Steam Cloud, read up on how the two methods differ, and determine which would be the best for your application.

First up is the Steam Cloud API.
The Cloud API provides a series of functions which allows you to directly integrate the Steam Cloud into your game. The Cloud API isolates individual Steam users files from each other and provides a greater level of control over the Steam Cloud.

The Steam Cloud API is exposed via the ISteamRemoteStorage API interface, and you can find example usage in the Steamworks API Example Application (SpaceWar) project.

The second is Steam Auto-Cloud.
Steam Auto-Cloud was designed for legacy games where you can not easily integrate the Steam Cloud API. It provides a quick and easy way to get started but lacks the power and flexibility that is available with the Steam Cloud API.

It is generally recommended that you use the Cloud API if possible as it allows for deeper integration and customization, and it enables you to best provide the high quality experience that Steam users have come to expect from the Steam Cloud.

Steam Auto-Cloud

Steam Auto-Cloud is an alternative to the Steam Cloud API that allows apps to use Steam Cloud without writing code or modifying the game in any way. It only requires that you specify the file groups which you want persisted to the Cloud. Steam will automatically sync the groups of files when the application launches and exits. Avoid machine specific configurations such as video quality.

Setup

After completing the Initial Setup the Steam Auto-Cloud configuration section will unlock on the Steam Cloud Settings page.

Root Paths describe groups of files which will be persisted to the Steam Cloud. Each Root Path can be as specific as a single file or as wide as all files under a given subfolder. Use a new path for each group of files to sync.

A Root Path is composed of 5 parts:
  1. Root

    This is a pre-determined list of paths where game saves are commonly located.
    RootSupported OSesCorresponding Path
    App Install DirectoryAll[Steam Install]/SteamApps/common/[Game Folder]/
    SteamCloudDocumentsAllPlatform specific path, e.g. on Linux: ~/.SteamCloud/[username]/[Game Folder]/
    WinMyDocumentsWindows%USERPROFILE%/My Documents/
    WinAppDataLocalWindows%USERPROFILE%/AppData/Local/
    WinAppDataLocalLowWindows%USERPROFILE%/AppData/LocalLow/
    WinAppDataRoamingWindows%USERPROFILE%/AppData/Roaming/
    WinSavedGamesWindows%USERPROFILE%/Saved Games/
    MacHomemacOS~/
    MacAppSupportmacOS~/Library/Application Support/
    MacDocumentsmacOS~/Documents/
    LinuxHomeLinux~/
    LinuxXdgDataHomeLinux$XDG\_DATA\_HOME/
  2. Subdirectory

    Subdirectory path to the clouded files relative to the Root. Use `.` if there is no subdirectory.

    Auto-Cloud special path values
    Auto-Cloud allows the use of unique Steam user identifiers in the Subdirectory path. This allows you to store save files for each Steam user on the computer separately. You can use ISteamUser::GetSteamID in your game to get the current users SteamID or AccountID to save to and read from.
    • {64BitSteamID} - Use this variable in the steam path to insert the users 64bit Steam ID. A 64 bit Steam ID looks like: 76561198027391269
    • {Steam3AccountID} - Use this variable in the steam path to insert the users Steam 3 Account ID. An Account ID looks like: 67125541
    Example: SavesDir/{64BitSteamID}
  3. Pattern

    File mask pattern to match. You can use * as a wildcard. If you want all files in the directory, just use *.

    Example: *.sav
  4. OS

    Sets the Operating Systems that these files will be synced from/to. This is only required if the files are OS specific, which is hopefully not the case!
  5. Recursive

    Include sub-directories when searching for matching files. This is useful for sub-directories with non-deterministic names such as non-steam user names or IDs. If it's using a Steam ID, then using the special path values in the Subdirectory field is highly recommended.

Root Overrides

If your application is cross-platform and requires different directories for each OS. You can use the Root Overrides functionality to specify an override the Root Paths that you set above.

The root paths specified above can be overridden to correspond to a different path on another OS. If you use Root Overrides, you must specify [All OSes] in the Root OS drop down above.

A Root Override consists of 5 parts.
  1. Original Root

    This corresponds to one of the Roots that you set above.
  2. OS

    The Operating System to apply the override on.
  3. New Root

    The new location that the Original Root maps to on the specified OS.
  4. Add/Replace Path

    This allows you to optionally add a subdirectory path which is inserted between the new root and the original subdirectory.
  5. Replace Path

    If enabled, it causes the path specified in Add/Replace Path to replace the original subdirectory entirely.

Example: Configuring Auto-Cloud for Unity Applications

The following is an example of setting up Auto-Cloud for use with Unity and the Application.persistentDataPath property where the value is different per OS. The Windows version is configured as the Root Path with the company in Unity set to DefaultCompany and the Project called AutocloudSample. On macOS and Linux/SteamOS, the alternate paths from Application.persistentDataPath are set in the Add/Replace Path field and Replace Path is enabled.

With these settings, Auto-Cloud files will be synchronized between the three folders as shown in the Preview samples.

Cloud_Unity_Auto-Cloud_Example.png

Pre-release Testing

If you are adding Steam Auto-Cloud to a game which is already released and you have enabled developer-only mode during the Initial Setup then you must complete some additional steps to test the functionality.
  1. Sign in to Steam with an account that owns a Developer Comp license for the app that you are testing.
  2. Open the Steam Console by navigating to steam://open/console in your browser.
  3. Enter testappcloudpaths <AppId> into the console with the given App ID that you are testing. Ex: testappcloudpaths 480
  4. Enter set_spew_level 4 4 into the console.
  5. Launch your app from Steam.
  6. Check the console for activity, If files already exist in the Auto-Cloud paths then you should see them being uploaded. Otherwise save some files from your app and then close it to trigger a sync.
  7. Go to another PC and repeat the steps above to test downloading the files from Steam Auto-Cloud.
  8. Be sure to test on all supported operating systems.
  9. Set testcloudapppaths 0 and set_spew_level 0 0 to end testing. You can restart the Steam client to get rid of the console tab.

Don't forget to disable developers-only mode and publish the changes when you're done testing.

Debugging

First, always ensure that you have published your changes on the Steam partner website and have waited up to 10 minutes or restarted your Steam client to receive the published changes.

If you run into issues with Steam Cloud you should check the log file located at %Steam Install%\logs\cloud_log.txt.

See Debugging the Steamworks API for additional information.