Огляд Steam Cloud

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

Якщо користувач змінює комп’ютер, то файли автоматично завантажуватимуться на новий комп’ютер перед запуском гри. Після цього гра може отримати доступ до файлів за допомогою хмарного API чи традиційним способом — шляхом прямого читання диску. Уникайте конкретних конфігурацій комп’ютера, як-от налаштувань відео.

Клієнт Steam виконує роботу з перевірки синхронізації файлів на всіх комп’ютерах, до яких користувач може мати доступ.

Користувачі можуть глобально вимкнути хмарну синхронізацію в налаштуваннях Steam на вкладці Steam Cloud, якщо вимкнуть параметр «Дозволити синхронізацію зі Steam Cloud тим продуктам, які це підтримують».

Користувачі також можуть вимикати синхронізацію з хмарою для певних ігор у властивостях кожної гри.

Примітки і корисні поради

Важливо пам’ятати, що Steam синхронізуватиме файли Steam Cloud користувача для вашої гри до та після кожного сеансу. Будь-які файли зі змінами під час сеансу вивантажуватимуться до хмарного сховища одразу потому. Якщо ваша гра записує до Steam Cloud дуже великі файли, або багато малих файлів, то це може суттєво відбитися на пропускній здатності мережі користувача, а також затримати вимкнення Steam чи перезапуск гри.

Невеликі файли зазвичай працюють краще. Якщо збережений стан певного користувача можна розділити на різні категорії (часто змінювані речі та рідко змінювані речі), то рекомендуємо використовувати різні файли для цих категорій. Таким чином незмінений стан не буде заново вивантажуватися після кожного сеансу.

Обмеження розміру файлів

Абсолютні обмеження розміру файлів для Steam Cloud можуть періодично змінюватися. Ось деякі поточні обмеження й пороги:

Розмір	Обмеження
100 МБ	Максимальний розмір для виклику ISteamRemoteStorage::FileWrite чи ISteamRemoteStorage::FileWriteStreamWriteChunk.
256 МБ	Це може призвести до неоптимального вибору кінцевої точки пам’яті в розташуванні користувача, що негативно впливатиме на швидкість вивантаження й завантаження.

Шляхи до файлів збереження

Коли вирішуєте, де записувати ваші файли збереження, переконайтеся, що шлях унікальний для поточного користувача Steam. Якщо потрібно, ви можете отримати унікальний SteamID користувача через ISteamUser::GetSteamID. Там ви можете отримати доступ до AccountID з GetAccountID(), що дозволяє отримати унікальну змінну для створення шляху до файлу збереження.

Міжплатформні збереження

Якщо ваша гра підтримується на кількох платформах або якщо ви плануєте додати таку підтримку в майбутньому, вам слід обміркувати налаштування Steam Cloud для вашої гри.

Якщо ви плануєте зчитувати/записувати файли безпосередньо через інтерфейс ISteamRemoteStorage, то зможете контролювати міжплатформну синхронізацію через ISteamRemoteStorage::SetSyncPlatforms. Для нового файлу стандартною є синхронізація з усіма платформами.

Якщо ви плануєте скористатися автоматичною хмарною синхронізацією Steam, варто мати на увазі кілька ключових моментів. Для нових файлів стандартною є синхронізація лише з налаштуваннями ОС у відповідному кореневому шляху автоматичної хмарної синхронізації. Це означає, що в разі встановлення різних кореневих тек для кожної ОС усі файли будуть розділені між платформами й не матимуть функціональності міжплатформного збереження.

Для ввімкнення міжплатформних збережень вам слід натомість визначити одну кореневу теку (наприклад, для Windows), а потім створити заміну кореневого каталогу для інших підтримуваних платформ. Файли, які знаходяться в кореневій теці й мають замінний кореневий каталог для іншої платформи, синхронізуватимуться з усіма платформами кореневої теки й замінних каталогів. Дивіться документацію автоматичної хмарної синхронізації Steam, щоби дізнатися більше.

Початкове налаштування

Спершу на сторінці налаштувань Steam Cloud у Steamworks (сторінка управління застосунком → «Змінити налаштування Steamworks» у розділі «Технічні інструменти» → вкладка «Застосунок» → «Steam Cloud») вам потрібно визначити квоту байтів на одного користувача та кількість файлів, дозволених одному користувачу.

Ці квоти вказуються для кожного користувача кожної гри з підтримкою хмарних збережень. Рекомендується вказувати доцільні для вашої гри значення.

ПРИМІТКА: не забудьте зберегти (внизу сторінки) й опублікувати свої оновлені налаштування. Після публікації піктограма хмарних збережень показуватиметься в клієнті Steam для всіх, хто володіє вашою грою.

Якщо ваша гра вже випущена, ви можете поставити прапорець «Увімкнути підтримку хмарного сховища тільки для розробників». У цьому режимі лише акаунти Steam із ліцензією розробника «Developer Comp» для вашого продукту бачитимуть піктограму хмарного сховища й зможуть використовувати Steam Cloud. Це корисно для безпечного тестування інтеграції Steam Cloud без ризику зіпсувати враження гравців. Це не діє для невипущених ігор, оскільки ними ще ніхто не володіє й не може мати доступ до відповідного хмарного сховища.

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

API Steam Cloud і хмарна автосинхронізація Steam

Steam надає два різні методи використання Steam Cloud. Ознайомтеся з їхніми відмінностями й визначте, який найкраще підійде для вашого застосунку.

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

Цей API стає доступним через інтерфейс ISteamRemoteStorage, і ви можете знайти зразок використання у проекті-прикладі.

Другий — це автоматична хмарна синхронізація Steam.
Ця функція була створена для ігор, які ви не хочете інтегрувати з API Steam Cloud. Вона надає легкий і швидкий спосіб хмарної синхронізації, але не має тих можливостей і гнучкості, що є в API Steam Cloud.

Якщо вам потрібна глибша інтеграція зі Steam Cloud (наприклад, для вибору того, які саме файли зберігаються в хмарі), тоді слід скористатися API Steam Cloud. Якщо ні, то вам достатньо використовувати хмарну автосинхронізацію Steam.

Автоматична хмарна синхронізація Steam

Автоматична хмарна синхронізація Steam — це альтернатива API Steam Cloud, яка дозволяє використовувати Steam Cloud без переписування коду чи інших модифікацій гри. Для цієї функції потрібно лише вказати групи файлів, які мають зберігатися в хмарі. Steam автоматично синхронізуватиме ці групи файлів, коли застосунок запускатиметься чи закриватиметься. Уникайте конкретних конфігурацій комп’ютера, як-от налаштувань якості відео.

Налаштування

Після завершення початкового налаштування на сторінці налаштувань Steam Cloud розблокується розділ для конфігурації автоматичної хмарної синхронізації Steam.

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

Коренева тека складається з 5 частин:

1. Корінь

   Це наперед визначений список тек, де зазвичай зберігаються ігрові збереження.
   

   Корінь	Підтримувані ОС	Шлях
   Директорія інсталяції застосунку	Усі	[Тека інсталяції Steam]\SteamApps\common\[Тека гри]\
   SteamCloudDocuments	Усі	Специфічний для платформи шлях, наприклад для Linux: ~/.SteamCloud/[ім’я_користувача]/[тека_гри]/
   WinMyDocuments	Windows	%USERPROFILE%\Документи\
   WinAppDataLocal	Windows	%USERPROFILE%\AppData\Local\
   WinAppDataLocalLow	Windows	%USERPROFILE%\AppData\LocalLow\
   WinAppDataRoaming	Windows	%USERPROFILE%\AppData\Roaming\
   WinSavedGames	Windows	%USERPROFILE%\Saved Games\
   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. Піддиректорія

   Шлях піддиректорії до файлів у хмарі відносно до кореневого каталогу. Якщо піддиректорії немає, то використовується «.»
   
   Особливий шлях для автоматичної хмарної синхронізації.
   Автоматична хмарна синхронізація дозволяє використовувати унікальні ідентифікатори користувачів Steam у шляху піддиректорії. Це дозволяє зберігати файли кожного користувача Steam на одному комп’ютері окремо. Ви можете використати ISteamUser::GetSteamID у своїй грі для отримання й збереження SteamID чи AccountID поточних користувачів.
   
   • {64BitSteamID} — використовуйте цю змінну для вставки в шлях 64-бітного SteamID. 64-бітний SteamID виглядає ось так: 76561198027391269
     
   • {Steam3AccountID} — використовуйте цю змінну для вставки в шлях AccountID у форматі Steam3. AccountID виглядає як: 67125541
     
   Приклад: SavesDir/{64BitSteamID}
   

3. Шаблон

   Шаблон, із яким має збігатися маска імені файлів. Можна використовувати * для будь-яких символів. Якщо вам потрібні всі файли в теці, використовуйте просто *.
   
   Приклад: *.sav
   

4. ОС

   Встановіть операційні системи, з якими синхронізуватимуться ці файли. Це необхідно якщо файли відносяться лише до певної ОС, що, сподіваємося, не так!
   

5. Включені піддиректорії

   Включати збіги файлів у піддиректоріях. Можна використовувати для піддиректорій з невизначеними назвами, як-от імена користувачів чи ID не зі Steam. Якщо використовується SteamID, то рекомендується використовувати спеціальні значення шляху в полі піддиректорії.

Заміна кореневого каталогу

Якщо ваш застосунок міжплатформний і для кожної ОС потрібні різні директорії, ви можете використовувати функцію заміни кореневого каталогу для перезапису вказаних вище кореневих тек.

Вказані вище кореневі теки можна замінити, щоби вони відповідали іншим текам на іншій ОС. Якщо використовуєте заміну кореневого каталогу, потрібно вказати [Усі ОС] в розкривному списку кореневої ОС вище.

Заміна кореневого каталогу складається з 5 частин.

1. Оригінальний кореневий каталог

   Відповідає одному зі встановлених вами вище значень кореневого каталогу.
   

2. ОС

   Операційна система, у якій застосовується зміна кореневого каталогу.
   

3. Новий кореневий каталог

   Новий шлях, котрий використовується замість оригінального в обраній ОС.
   

4. Додати/замінити шлях

   Дозволяє за потреби додати шлях піддиректорії, що вставляється між новим кореневим каталогом та оригінальною піддиректорією.
   

5. Замінити шлях

   Якщо ввімкнено, піддиректорія, вказана в розділі «Додати/Замінити шлях», не доповнить, а повністю замінить оригінальну піддиректорію.

Приклад: конфігурація автосинхронізації для застосунків Unity

Далі ми покажемо приклад налаштування хмарної автосинхронізації для використання з Unity та властивістю Application.persistentDataPath, де значення різне для кожної ОС. Версія для Windows налаштована так, що кореневу теку компанії в Unity встановлено як DefaultCompany, а проект названо AutocloudSample. На macOS і Linux/SteamOS альтернативні шляхи з Application.persistentDataPath встановлені в полі «Додати/замінити шлях» й заміну шляху ввімкнено.

З цими налаштуваннями файли автоматичної хмарної синхронізації синхронізуються між трьома теками, як це показано в прикладах попереднього перегляду.

Тестування перед випуском

Якщо ви додаєте автоматичну хмарну синхронізацію Steam до гри, яка вже вийшла, і ввімкнули режим тільки для розробників під час початкового налаштування, то вам потрібно здійснити деякі додаткові кроки для перевірки функціональності.

1. Увійдіть у Steam з акаунта, що володіє застосунком, який ви тестуєте.
   
2. Відкрийте консоль Steam переходом до steam://open/console у вашому веб-оглядачі.
   
3. Введіть у консолі testappcloudpaths <AppId> з AppID застосунку, який ви тестуєте. Приклад: testappcloudpaths 480
   
4. Введіть у консолі set_spew_level 4 4.
   
5. Запустіть ваш застосунок у Steam.
   
6. Якщо в теках хмарної автосинхронізації вже наявні файли, то в консолі ви побачите їхнє вивантаження. Якщо ні, то збережіть кілька файлів цього застосунку й потім закрийте його, щоби запустити синхронізацію.
   
7. Перейдіть на інший ПК і повторіть кроки вище, щоби перевірити, як працює завантаження файлів автоматичної хмарної синхронізації.
   
8. Не забудьте протестувати на всіх підтримуваних операційних системах.
   
9. Введіть testappcloudpaths 0 та set_spew_level 0 0 для завершення тестування. Перезапустіть клієнт Steam для закриття консолі.

Не забудьте вимкнути режим лише для розробників та опублікувати зміни, коли завершите тестування.

Динамічна хмарна синхронізація

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

Перегляньте наше оголошення для отримання докладнішої інформації про цю функцію та користування нею.

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

Для докладнішої інформації дивіться документацію 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> з AppID застосунку, який ви тестуєте. Приклад: @cloud_testdynamicsyncapp 480
   
4. Запустіть ваш застосунок у Steam.
   
5. Пограйте, скільки потрібно.
   
6. У консолі Steam уведіть prepare_for_suspend. Steam призупинить процес вашої гри й вивантажить усі змінені файли до Steam Cloud.
   
7. Необов’язково: запустіть гру на іншому пристрої, пройдіть ще якусь частину, а потім вийдіть і дайте клієнту Steam вивантажити цей поступ до Steam Cloud.
   
8. Поверніться на початковий пристрій і в консолі Steam уведіть resume_suspended_games. Це синхронізує всі необхідні файли зі Steam Cloud, відправить потрібні виклики API вашій грі, а потім відновить процес гри.

Для локального тестування зі Steam Deck:

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

Налагодження

Завжди перевіряйте, чи ви опублікували свої зміни на партнерському сайті, а також зачекайте до 10 хвилин або перезапустіть свій клієнт Steam, щоб отримати опубліковані зміни.

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

Для докладнішої інформації перегляньте розділ про налагодження.