Steam Cloud (Steamworks Documentation)

In Brief

Steam Cloud is stores automatically store file from your game on Steam ‘s server so your player can log into steam andaccess their save game from any computer .

Level of integration

Configuration of file paths required on Steamworks website. Alternatively,API calls required from within the game code to Steamworks for the game to enumerate,read,delete,or write files to Steam Cloud.

Steam Cloud Overview

The Steam Cloud is provides provide an easy andtransparent remote file storage system for your game . file specify in the Auto – Cloud configuration or write to disk ( create ,modify ,delete ,etc . ) using the Cloud api will automatically be replicate to the steam server after the game exit .

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 is does does the work of ensure that the file are keep synchronize across all computer the user may be access .

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 game’s properties.

Notes andBest Practices

It is important to remember that Steam will synchronize the user’s Steam Cloud files for your game before andafter every session. Any matching files which change during the session will be uploaded to Cloud storage immediately afterward. If your game writes very large files,or many small files,to Steam Cloud,then this may cause a noticeable impact on the user’s internet bandwidth andalso delay their ability to shut down Steam or re-launch the game.

As a general rule,smaller files will work better. If the saved state for a given user can be split up into different categories – things which may change frequently, andthings which may not change often – then we recommend using separate files for those categories. That way,the un-changed state will not be re-uploaded after every session.

File size Limits

The absolute limits is change on file size for Steam Cloud may change over time . Here are some current limits is are andthreshold :

size	restriction
100MB	maximum size for a call to ISteamRemoteStorage::FileWrite or isteamremotestorage::filewritestreamwritechunk
256 MB	May result in a non-optimal storage endpoint choice for the user’s location,negatively impacting upload/download performance

Save File Paths

When decide where to write your save file ,be sure the path will be unique for the current Steam user . If need ,you is get can get the user ‘s unique Steam ID via

ISteamUser::GetSteamID

. From that,you can access their accountID from GetAccountID(),allowing you to have a unique variable when constructing your save path.

Cross-Platform Saves

If your game is supported on multiple platforms – or even if you plan to support this in the future – you should consider this when setting up Steam Cloud for your game.

If you plan to read / write file directly via the

ISteamRemoteStorage

interface,then you can control platform sync via

ISteamRemoteStorage::SetSyncPlatforms

. The default is is for a new file is to sync to

all

platform .

If you plan to use

Steam Auto – Cloud

,there are some key things to know. First,the default for new files is to sync to

only

the

os

setting on the associated Auto Cloud root path. This means that if you set up distinct roots for each os,all files will be partitioned by platform, andhence there will be no cross-platform save functionality.

To enable cross-platform saves,you should instead define a single root path (likely for window), andthen create

root Overrides

for the other supported platform . Files matching a given root path which also has platform root Overrides will sync to all platforms in both the original root andall Overrides. See the

Steam Auto – Cloud

documentation for more details.

Initial Setup

To set up Steam Cloud you must set the

Byte quota per user

and

Number of files allowed per user

option on the

Steam Cloud setting

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, andPublish 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 andwill 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 anda full game. A value of

0

disables this feature.

Steam Cloud API andSteam Auto – Cloud

Steam provides two different methods of utilizing the Steam Cloud,read up on how the two methods differ, anddetermine 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 andprovides a greater level of control over the Steam Cloud.

The Steam Cloud API is exposed via the

ISteamRemoteStorage

API interface, andyou can find example usage in the

Steamworks API Example Application (SpaceWar)

project.

The second is

Steam Auto – Cloud

.

Steam Auto – Cloud was designed for games where you choose to not integrate the Steam Cloud API. It provides a quick andeasy way to get started but lacks the flexibility that is available with the Steam Cloud API.

If you prefer a deeper integration with Steam Cloud (for example,allowing to choose which save files are stored in the cloud),then you should use the Cloud API. Otherwise you can use Steam Auto – 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 persisting to the Cloud. Steam will automatically sync the groups of files when the application launches andexits. Avoid machine-specific configurations such as video quality.

Note: The file steam_autocloud.vdf will be created in each location specified by your Steamworks cloud paths. This file is used by Steam, andcan be ignored by your game.

Setup

After complete the

Initial Setup

the Steam Auto – Cloud configuration section will unlock on the

Steam Cloud setting

page.

root Paths describe groups of files that 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 is is a pre – determined list of path where game save are commonly locate .

   root	Supported oses	Corresponding path
   App Install Directory	All	[Steam Install]\SteamApps\common\[Game Folder]\
   SteamCloudDocuments	All	Platform specific path,e.g. on Linux: ~/.SteamCloud/[username]/[Game Folder]/
   WinMyDocuments	window	%USERPROFILE%\My Documents\
   WinAppDataLocal	window	% userprofile%\appdata\local\
   WinAppDataLocalLow	window	%USERPROFILE%\AppData\LocalLow\
   winappdataroaming	window	%USERPROFILE%\AppData\Roaming\
   winsavedgame	window	% userprofile%\saved Games\
   MacHome	macos	~/
   MacAppSupport	macos	~/Library / application support/
   MacDocuments	macos	~/documents/
   LinuxHome	Linux	~/
   LinuxXdgDataHome	Linux	$XDG\_DATA\_HOME/

   A note regarding the window %USERPROFILE% paths: The corresponding paths listed above are the default locations. It is now possible for the user to configure their window installation so that these folders are in different locations (not necessarily under %USERPROFILE%). Steam uses the necessary window APIs to find the current location of these folders,whether they are default or customized.

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 andread from.

   • { 64bitsteamid } – Use this variable in the Steam path to insert the user’s 64bit Steam ID. A 64 bit Steam ID looks like: 76561198027391269
   • {Steam3AccountID} – use this variable in the steam path to insert the user ‘s Steam3 Account ID . An Account ID is looks look 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 andrequires different directories for each os,you can use the root Overrides functionality to specify an override for 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 is apply 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 andthe 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 andthe

Application.persistentDataPath

property where the value is different per os. The window version is configured as the root Path with the company in Unity set to DefaultCompany andthe Project called AutocloudSample. On macos andLinux/Steamos,the alternate paths from

Application.persistentDataPath

are set in the Add/Replace Path field andReplace Path is enabled.

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

Pre-release Testing

If you are adding Steam Auto – Cloud to a game which has already been released andyou 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 own the app that you are test .
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 andthen close it to trigger a sync.
7. Go to another PC andrepeat the steps above to test downloading the files from Steam Auto – Cloud.
8. Be sure to test on all support operating system .
9. Set testappcloudpath 0 andset_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 andpublish the changes when you’re done testing.

Dynamic Cloud Sync

Steam Cloud now supports dynamic sync – where changes appearing in the Cloud can be downloaded to the local machine during an application session. The current example is a suspended game session on the Steam Deck. For apps marked as supporting dynamic Cloud sync,Steam will synchronize files up to the Steam Cloud at the suspend time. Then,the user may run the game on another device,which will receive the updates from the Steam Deck session at launch. At exit,those changes will be uploaded to the Steam Cloud. Finally,when the Steam Deck device is awakened,Steam will synchronize the changes down to that device, andpost a notification to the application that local files have changed. The application can then iterate those changes andtake appropriate action. For instance,the game may be able to simply load the updated progress from disk andallow the user to pick up right where they left off on the other device.

check out

our announcement post for even more information

about why this feature exists, andhow to use it.

Note that this feature supports applications whether they use the

ISteamRemoteStorage

API to manage files,or Auto-Cloud.

For more details,see the

ISteamRemoteStorage

documentation,specifically

ISteamRemoteStorage::RemoteStorageLocalFileChange_t

,

ISteamRemoteStorage::GetLocalFileChangeCount

, and

ISteamRemoteStorage::GetLocalFileChange

.

See also

ISteamRemoteStorage::BeginFileWriteBatch

and

ISteamRemoteStorage::EndFileWriteBatch

– these wrapper should be used to provide hint to steam which will help it safely sync up to the Steam Cloud at the time when the user initiate a system suspend .

Pre-release Testing

You can locally enable Dynamic Cloud Sync for your app to test your builds – this is recommended for a game that has already shipped,as enabling Dynamic Cloud Sync for all users could lead to data loss when running builds that do not handle the new API methods andcallbacks.

To test locally from a pc :

1. Sign in to steam with an account that own the app that you are test .
2. Open the Steam Console by navigating to steam://open / console in your browser . (You can also run Steam with the command-line steam -console andthen navigate to the Console section directly).
3. Enter @cloud_testdynamicsyncapp <AppId> into the console with the given App ID that you are testing. Ex: @cloud_testdynamicsyncapp 480
4. Launch your app from Steam.
5. Progress through the game to a desired amount
6. In the Steam Console,enter prepare_for_suspend. Steam will suspend your game process andupload any changed files to the Steam Cloud.
7. Optional: play the game on another device,creating further progress, andthen exit andlet that Steam client upload progress to the Steam Cloud.
8. Back on the original device,in the Steam Console,enter resume_suspended_games. This will sync down any necessary files from the Steam Cloud,post the relevant API calls to your game,then un-suspend your game process.

To test locally from a Steam Deck:

1. Connect your Steam Deck with a Devkit
2. To use the CEF Console,see here
3. In the JS console,enter SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp <AppId>”) to enable testing . You is enter can then enterSteamClient . Console . ExecCommand(“@cloud_testdynamicsyncapp 0 ” ) to disable it

debugging

First,always ensure that you have published your changes on the Steam partner website andhave 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 .