Обзор Steam Cloud

Облачная синхронизация Steam Cloud представляет собой простую и прозрачную систему удаленного хранения файлов для игр. Файлы, указанные при настройке Auto-Cloud или записанные на диск (созданные, изменённые, удалённые и т. д.) с использованием Cloud API, автоматически будут продублированы на серверах Steam после выхода из игры.

Если пользователь меняет компьютер, все файлы автоматически будут загружены на новую машину перед запуском игры. После этого игра получит доступ к файлам либо через API Steam Cloud, либо напрямую с диска. Avoid machine-specific configurations such as video settings.

Клиент Steam берет на себя работу по синхронизации файлов на всех компьютерах пользователя.

Пользователи могут отключить синхронизацию для всех игр в настройках Steam, сняв галочку «Включить синхронизацию со Steam Cloud для поддерживаемых приложений».

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

Замечания и рекомендации

Помните, что Steam синхронизирует пользовательские файлы Steam Cloud для вашей игры до и после каждой сессии. Все соответствующие файлы, которые изменятся во время сессии, будут загружены в Cloud сразу по ее окончании. Если ваша игра записывает очень большие файлы или много маленьких файлов в Steam Cloud, это может значительно влиять на пропускную способность сети пользователя, а также создавать задержку при попытке выключить Steam или перезагрузить игру.

В целом, предпочтительнее использовать файлы маленького размера. Если сохранение для конкретного пользователя может быть разделено на категории: всё, что может часто меняться, и то, что не будет меняться часто, мы рекомендуем сохранять отдельные файлы для этих категорий. В таком случае неизменённая часть сохранения не будет загружаться после каждой сессии.

Ограничения размеров файлов

Максимальный размер файла для Steam Cloud может со временем измениться. Вот некоторые текущие лимиты и пороговые значения:

Размер	Ограничение
100 Мб	Максимальный размер вызова ISteamRemoteStorage::FileWrite или ISteamRemoteStorage::FileWriteStreamWriteChunk
256 Мб	Может привести к неоптимальному выбору конечной точки хранилища пользователя, что негативно скажется на скорости загрузки/выгрузки

Save File Paths

When deciding where to write your save files, be sure the path will be unique for the current Steam user. If needed, you 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 files directly via the ISteamRemoteStorage interface, then you can control platform sync via ISteamRemoteStorage::SetSyncPlatforms. The default for a new file is to sync to all platforms.

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, and hence there will be no cross-platform save functionality.

To enable cross-platform saves, you should instead define a single Root path (likely for Windows), and then create Root Overrides for the other supported platforms. Files matching a given Root path which also has platform Root Overrides will sync to all platforms in both the original Root and all Overrides. See the Steam Auto-Cloud documentation for more details.

Начальная настройка

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.

ВНИМАНИЕ: 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.

API Steam Cloud и 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 Приложение-образец с API Steamworks (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 and easy 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 and exits. Avoid machine-specific configurations such as video quality.

Setup

After completing the Начальная настройка the Steam Auto-Cloud configuration section will unlock on the Steam Cloud Settings 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. Корень

   Это предопределенный список путей, где обычно сохраняются игры.
   

   Корень	Поддерживаемые ОС	Путь
   Директория установки приложения	Все	[Папка установки Steam]\SteamApps\common\[Папка игры]\
   SteamCloudDocuments	Все	Специфический для платформы путь, к примеру на Linux: ~/.SteamCloud/[username]/[Game Folder]/
   WinMyDocuments	Windows	%USERPROFILE%\Документы\
   WinAppDataLocal	Windows	%USERPROFILE%\AppData\Local\
   WinAppDataLocalLow	Windows	%USERPROFILE%\AppData\LocalLow\
   WinAppDataRoaming	Windows	%USERPROFILE%\AppData\Roaming\
   WinSavedGames	Windows	%USERPROFILE%\Сохраненные игры\
   MacHome	macOS	~/
   MacAppSupport	macOS	~/Library/Application Support/
   MacDocuments	macOS	~/Documents/
   LinuxHome	Linux	~/
   LinuxXdgDataHome	Linux	$XDG\_DATA\_HOME/

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

2. Подкаталог

   Путь подкаталога к файлам в облаке является относительным по отношению к корню. Если подкаталога нет, используется `.`
   
   Специальный путь при автосинхронизации
   Auto-Cloud allows the use of unique Steam user identifiers in the Subdirectory path. Это позволяет хранить файлы каждого пользователя Steam на одном компьютере отдельно. Для получения SteamID или AccountID текущего пользователя при сохранении и чтении файлов используется ISteamUser::GetSteamID.
   
   • {64BitSteamID} - Use this variable in the Steam path to insert the user's 64bit Steam ID. 64-битный SteamID выглядит так: 76561198027391269
     
   • {Steam3AccountID} - Use this variable in the Steam path to insert the user's Steam3 Account ID. AccountID выглядит так: 67125541
     
   Пример: SavesDir/{64BitSteamID}
   

3. Шаблон

   Это шаблон, которому должна соответствовать маска имени файлов. Можно использовать * в качестве символа-джокера. Если вам нужны все файлы в папке, просто используйте *.
   
   Пример: *.sav
   

4. ОС

   Здесь выбираются операционные системы, для которых будут синхронизироваться файлы. Это необходимо, если файлы относятся только к той или иной операционной системе. Надеемся, что это не так!
   

5. Вкл. подпапки

   Искать подходящие файлы во вложенных папках. Это можно использовать для подпапок с неопредленными названиями, такими как имена пользователей или ID извне Steam. Если используется Steam ID, рекомендуется использовать специальные значения пути в поле «Подкаталог».

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 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. Исходный корень

   Соответствует одному из значений для пункта «Корень».
   

2. ОС

   Операционная система, в которой применяется замена корня.
   

3. Новый корень

   Новый путь, который используется на месте исходного в определённой выше ОС.
   

4. Добавление или замена пути

   Эта настройка позволяет при необходимости добавить путь подкаталога, который вставляется между новым путём и исходным подкаталогом.
   

5. Замена пути

   При включении подкаталог, определённый в поле «Добавление или замена пути», не дополнит, а заменит корневой подкаталог.

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.

Pre-release Testing

If you are adding Steam Auto-Cloud to a game which has already been released and you have enabled developer-only mode during the Начальная настройка then you must complete some additional steps to test the functionality.

1. Sign in to Steam with an account that owns the app that you are testing.
   
2. Откройте консоль Steam (steam://open/console в браузере).
   
3. Введите в консоль testappcloudpaths <AppId>, где App ID — номер приложения, которое вы тестируете. К примеру: testappcloudpaths 480
   
4. Введите в консоль set_spew_level 4 4.
   
5. Запустите приложение из Steam.
   
6. Если в каталогах, которые использует функция Auto-Cloud, уже находятся файлы, в консоли вы увидите их загрузку. В противном случае сохраните несколько файлов для этого приложения и затем закройте его, чтобы запустить синхронизацию.
   
7. Перейдите на другой компьютер и повторите описанные выше действия, чтобы протестировать, как работает загрузка из Auto-Cloud.
   
8. Протестируйте на всех операционных системах, которые поддерживает приложение.
   
9. Для завершения тестирования введите testappcloudpaths 0 и set_spew_level 0 0. Перезагрузите клиент Steam для закрытия консоли.

Don't forget to disable developers-only mode and publish 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, and post a notification to the application that local files have changed. The application can then iterate those changes and take appropriate action. For instance, the game may be able to simply load the updated progress from disk and allow 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, and how 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 wrappers should be used to provide hints to Steam which will help it safely sync up to the Steam Cloud at the time when the user initiates 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 and callbacks.

To test locally from a PC:

1. Sign in to Steam with an account that owns the app that you are testing.
   
2. Откройте консоль Steam (steam://open/console в браузере). (You can also run Steam with the command-line steam -console and then 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. Запустите приложение из 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 and upload any changed files to the Steam Cloud.
   
7. Optional: play the game on another device, creating further progress, and then exit and let 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 can then enter SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp 0”) to disable it

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 Отладка API Steamworks for additional information.