Документация Steamworks
Steam Cloud
Вкратце
Steam Cloud автоматически сохраняет файлы из вашей игры на серверах Steam, так что игроки могут войти в Steam и получить доступ к сохраненным играм с любого компьютера.
Уровень интеграции
На сайте Steamworks требуется настройка путей файлов. Для загрузки, отправки, перечисления и удаления файлов также может потребоваться внедрить в игровой код вызовы API Steamworks.

Обзор Steam Cloud

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

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

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

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

Пользователи также могут отключить синхронизацию для конкретной игры в ее настройках.

Spacewar_Cloud_Properties.png

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


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

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

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


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

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

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

Для настройки Steam Cloud нужно установитьквоту байтов на одного пользователя иквоту файлов на одного пользователя на странице настроек Steam Cloud в разделе управления приложением Steamworks.

Квоты устанавливаются для всех игр с поддержкой синхронизации из расчёта на каждого пользователя в игре. Рекомендуется установить значения, приемлемые для вашей игры.

ВНИМАНИЕ: Не забудьте нажать кнопку «Сохранить» внизу страницы и опубликовать изменённые настройки. После публикации значок синхронизации будет виден в клиенте Steam всем пользователям, у которых есть ваша игра.

Если игра уже была выпущена, вы можете поставить галочку напротив опции «Включить поддержку синхронизации только для разработчиков». Если же включен режим для разработчиков, только аккаунты Steam с лицензией «Комплект разработчика» для вашего продукта будут видеть значок синхронизации и смогут использовать Steam Cloud. Это удобно в тех случаях, когда необходимо протестировать интеграцию синхронизации не сломав ничего для пользователей. Это никак не повлияет на неопубликованные игры, поскольку ими ещё никто не владеет, а значит ни у кого не будет доступа к облачному хранилищу конкретного AppID.

Вы можете разделить облачное хранилище между двумя приложениями, заполнив поле APP ID общего хранилища. Как правило, эта функция используется для сохранения файлов, общих для демоверсии и полной версии игры. Значение 0 отключает эту функцию.

API Steam Cloud и Steam Auto-Cloud

Steam предлагает два способа использования Steam Cloud. Ознакомьтесь с их основными различиями и определите, который лучше подходит для вашего приложения.

Первый — API синхронизации Steam Cloud.
В Cloud API представлены функции, которые позволяют интегрировать Steam Cloud непосредственно в игру. API Cloud изолирует друг от друга файлы отдельных пользователей Steam и предоставляет больший уровень контроля над синхронизацией.

API Steam Cloud предоставляются через интерфейс ISteamRemoteStorage. Вы можете найти пример его использования в проекте Приложение-образец с API Steamworks (SpaceWar).

Второй — автосинхронизация Steam Auto-Cloud.
Steam Auto-Cloud была разработана для тех игр, в которых вы хотите обойтись без интеграции Cloud API. Она позволяет быстро начать работу, но не обладает гибкостью, присущей Cloud API.

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

Steam Auto-Cloud

Steam Auto-Cloud является альтернативой API синхронизации, которая позволяет использовать облачное хранилище без необходимости писать код или вносить изменения в игру. Все, что нужно, это указать группы файлов, которые вы хотите сохранять в облаке. Steam автоматически синхронизирует эти группы во время запуска приложения и выхода из него. Избегайте синхронизации настроек, специфичных для каждого компьютера, например таких, как качество видео.
Note: The file steam_autocloud.vdf will be created in each location specified by your Steamworks cloud paths. This file is used by Steam, and can be ignored by your game.

Настройка

After completing the Начальная настройка 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. Корень

    Это предопределенный список путей, где обычно сохраняются игры.
    КореньПоддерживаемые ОСПуть
    Директория установки приложенияВсе[Папка установки Steam]\SteamApps\common\[Папка игры]\
    SteamCloudDocumentsВсеСпецифический для платформы путь, к примеру на Linux: ~/.SteamCloud/[username]/[Game Folder]/
    WinMyDocumentsWindows%USERPROFILE%\Документы\
    WinAppDataLocalWindows%USERPROFILE%\AppData\Local\
    WinAppDataLocalLowWindows%USERPROFILE%\AppData\LocalLow\
    WinAppDataRoamingWindows%USERPROFILE%\AppData\Roaming\
    WinSavedGamesWindows%USERPROFILE%\Сохраненные игры\
    MacHomemacOS~/
    MacAppSupportmacOS~/Library/Application Support/
    MacDocumentsmacOS~/Documents/
    LinuxHomeLinux~/
    LinuxXdgDataHomeLinux$XDG\_DATA\_HOME/
  2. Подкаталог

    Путь подкаталога к файлам в облаке является относительным по отношению к корню. Если подкаталога нет, используется `.`

    Специальный путь при автосинхронизации
    Auto-Cloud позволяет использовать индентификаторы пользователей Steam в пути Подкаталог. Это позволяет хранить файлы каждого пользователя Steam на одном компьютере отдельно. Для получения SteamID или AccountID текущего пользователя при сохранении и чтении файлов используется ISteamUser::GetSteamID.
    • {64BitSteamID} — эта переменная используется для вставки в путь 64-битного SteamID. 64-битный SteamID выглядит так: 76561198027391269
    • {Steam3AccountID} — эта переменная используется для вставки в путь AccountID. AccountID выглядит так: 67125541
    Пример: SavesDir/{64BitSteamID}
  3. Шаблон

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

    Пример: *.sav
  4. ОС

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

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

Замена корня

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

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

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

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

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

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

Пример: настройка Auto-Cloud для приложений Unity

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

Предрелизное тестирование

If you are adding Steam Auto-Cloud to a game which is already 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 , где App ID — номер приложения, которое вы тестируете. К примеру: testappcloudpaths 480
  4. Введите в консоль set_spew_level 4 4.
  5. Запустите приложение из Steam.
  6. Если в каталогах, которые использует функция Auto-Cloud, уже находятся файлы, в консоли вы увидите их загрузку. В противном случае сохраните несколько файлов для этого приложения и затем закройте его, чтобы запустить синхронизацию.
  7. Перейдите на другой компьютер и повторите описанные выше действия, чтобы протестировать, как работает загрузка из Auto-Cloud.
  8. Протестируйте на всех операционных системах, которые поддерживает приложение.
  9. Для завершения тестирования введите testcloudapppaths 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.

Currently, the ability to flag an application as supporting dynamic Cloud sync is only available to Valve admins. Get in touch with your Valve contacts for more detail.

Note that this feature supports applications whether they use the ISteamRemoteStorage API to manage files, or AutoCloud.

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.

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.