Обзор Steam Cloud

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

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

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

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

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

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

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

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

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

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

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

Пути файлов сохранений

Выбирая, куда записывать файлы сохранений, нужно убедиться, чтобы путь был уникальным для текущего пользователя Steam. При необходимости уникальный Steam ID можно получить с помощью запроса ISteamUser::GetSteamID. Имея Steam ID пользователя, вы можете узнать его accountID через запрос GetAccountID(), что даст вам уникальную переменную для создания пути файлов сохранений.

Кроссплатформенные сохранения

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

Если вы планируете выполнять чтение и запись файлов напрямую через интерфейс ISteamRemoteStorage, то можете задать параметры синхронизации между платформами с помощью ISteamRemoteStorage::SetSyncPlatforms. По умолчанию новый файл синхронизируется на всех платформах.

Если же вы планируете использовать Steam Auto-Cloud, тогда вам нужно запомнить несколько важных моментов. Во-первых, по умолчанию новые файлы синхронизируются только на платформе, указанной в части OS корневого пути Auto Cloud. Это означает, что если вы настроите отдельные корневые пути для каждой ОС, все файлы будут разделены по платформам, а следовательно — у вас не будет работать функционал кроссплатформенных сохранений.

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

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

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

Эти квоты действуют для каждой игры с поддержкой Steam Cloud и являются отдельными для каждого пользователя. Рекомендуется задавать значения в разумных пределах.

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

Если ваша игра уже выпущена, можете поставить галочку возле пункта ‭«Включить синхронизацию только для разработчиков». В этом режиме только пользователи с активированной лицензией Developer Comp для вашей игры увидят иконку Steam Cloud и смогут использовать эту функцию. Данный режим подойдёт для безопасного тестирования интеграции Steam Cloud без ущерба для обычных пользователей. Опция не влияет на невыпущенные игры, поскольку ими ещё никто не владеет, а следовательно — ни у кого не будет доступа к облачному хранилищу приложения.

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

API Steam Cloud и Steam Auto-Cloud

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

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

Доступ к API Steam Cloud можно получить через API-интерфейс ISteamRemoteStorage. Пример использования есть на странице «Приложение-образец с API Steamworks (SpaceWar)».

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

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

Steam Auto-Cloud

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

Настройка

После выполнения инструкций из раздела «Начальная настройка» на странице «Настройки Steam Cloud» появится раздел настройки Steam Auto-Cloud.

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

Корневой путь состоит из 5 частей:

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/

   
   Примечание о путях %USERPROFILE% на Windows: перечисленные выше пути являются стандартными. Пользователь может настроить установку Windows так, чтобы эти папки находились в других местах (необязательно в папке %USERPROFILE%). Steam использует API-интерфейсы Windows для поиска текущего местонахождения этих папок — будь оно стандартное или заданное пользователем.
   
   

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

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

3. Шаблон

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

4. ОС

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

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

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

Замена корня

Если ваше приложение кроссплатформенное и требует отдельных директорий для каждой ОС, вы можете воспользоваться функционалом замены корня для изменения заданных корневых путей.

Тогда обозначенные выше корневые пути будут заменяться в зависимости от операционной системы. Чтобы использовать эту функцию, выберите [Все ОС] в пункте «ОС».

Замена корня состоит из 5 частей.

1. Исходный корень

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

2. ОС

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

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

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

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

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

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

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

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

Ниже приведён пример настройки Auto-Cloud для использования с Unity и свойством Application.persistentDataPath, значение которого разное для каждой ОС. Путь версии для Windows мы указали в качестве корневого, компания в Unity у нас называется DefaultCompany, а проект — AutocloudSample. Для macOS и Linux/SteamOS мы указываем альтернативные пути (полученные из ответа на запрос Application.persistentDataPath) в поле ‭«Добавление/замена пути», а также ставим галочку возле ‭«Заменить путь».

При таких настройках файлы Auto-Cloud будут синхронизироваться между всеми тремя папками, как показано в примерах предпросмотра.

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

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

1. Войдите в Steam, используя аккаунт, которому принадлежит тестируемое приложение.
   
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 для закрытия консоли.

Не забудьте отключить режим «только для разработчиков» и опубликовать изменения, когда закончите тестирование.

Динамическая облачная синхронизация

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

Подробнее о том, зачем нужна эта функция и как ею пользоваться, читайте в нашей публикации.

Обратите внимание, что данная функция поддерживается в приложениях независимо того, какой способ управления файлами в них используется — API ISteamRemoteStorage или Auto-Cloud.

Подробнее читайте в документации ISteamRemoteStorage — в частности, разделы о ISteamRemoteStorage::RemoteStorageLocalFileChange_t, ISteamRemoteStorage::GetLocalFileChangeCount и ISteamRemoteStorage::GetLocalFileChange.

Также ознакомьтесь с информацией о функциях-обёртках ISteamRemoteStorage::BeginFileWriteBatch и ISteamRemoteStorage::EndFileWriteBatch. Их нужно использовать, чтобы дать Steam подсказки, которые помогут ему безопасно синхронизироваться со Steam Cloud, когда пользователь приостанавливает работу системы.

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

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

Локальное тестирование на компьютере:

1. Войдите в Steam, используя аккаунт, которому принадлежит тестируемое приложение.
   
2. Откройте консоль Steam (steam://open/console в браузере). (Вы также можете запустить Steam с помощью команды steam -console, а затем перейти в раздел ‭«Консоль».)
   
3. Введите в консоли @cloud_testdynamicsyncapp <AppId>, где App ID — номер приложения, которое вы тестируете. Пример: @cloud_testdynamicsyncapp 480
   
4. Запустите приложение из Steam.
   
5. Пройдите определённый отрезок игры.
   
6. Введите prepare_for_suspend в консоли Steam. Клиент приостановит игровой процесс и загрузит все изменённые файлы в Steam Cloud.
   
7. По желанию: сыграйте на другом устройстве, пройдя ещё один отрезок, а затем выйдите и дайте клиенту Steam загрузить данные о прогрессе в Steam Cloud.
   
8. На первом устройстве введите resume_suspended_games в консоли Steam. Это синхронизирует все необходимые файлы из облака, отправит соответствующие API-запросы вашей игре, а затем возобновит игровой процесс.

Локальное тестирование на Steam Deck:

1. Подключите свой Steam Deck с помощью комплекта разработчика.
   
2. Откройте консоль CEF, следуя инструкциям.
   
3. В консоли JS введите SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp <AppId>”), чтобы включить тестирование. Чтобы его отключить, введите SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp 0”).

Отладка

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

При возникновении проблем со Steam Cloud проверьте файл журнала, расположенный в %Steam Install%\logs\cloud_log.txt.

Для получения дополнительной информации см. статью «Отладка API Steamworks».