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

Огляд Steam Cloud

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

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

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

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

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

Spacewar_Cloud_Properties.png

Примітки і найкращі практики


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

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Встановлення

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

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

Кореневий шлях складається з 5 частин:
  1. Корінь

    Це наперед визначений список шляхів, де зазвичай зберігаються ігрові збереження.
    КоріньПідтримувані ОСШлях
    Директорія інсталяції застосункуУсе[Тека інсталяції Steam]\SteamApps\common\[Тека гри]\
    SteamCloudDocumentsУсеСпецифічний для платформи шлях, наприклад для Linux: ~/.SteamCloud/[ім’я_користувача]/[тека_гри]/
    WinMyDocumentsWindows%USERPROFILE%\Документи\
    WinAppDataLocalWindows%USERPROFILE%\AppData\Local\
    WinAppDataLocalLowWindows%USERPROFILE%\AppData\LocalLow\
    WinAppDataRoamingWindows%USERPROFILE%\AppData\Roaming\
    WinSavedGamesWindows%USERPROFILE%\Saved Games\
    MacHomemacOS~/
    MacAppSupportmacOS~/Library/Application Support/
    MacDocumentsmacOS~/Documents/
    LinuxHomeLinux~/
    LinuxXdgDataHomeLinux$XDG\_DATA\_HOME/
  2. Піддиректорія

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

    Особливий шлях для автосинхронізації
    Хмарна автосинхронізація дозволяє використовувати унікальні ідентифікатори користувачів Steam у шляху піддиректорії. Це дозволяє зберігати файли кожного користувача Steam на одному комп’ютері окремо. Ви можете використати ISteamUser::GetSteamID у своїй грі для отримання й збереження SteamID чи AccountID поточних користувачів.
    • {64BitSteamID} — використовуйте цю змінну для вставки в шлях 64-бітного SteamID. 64-бітний SteamID виглядає ось так: 76561198027391269
    • {Steam3AccountID} — використовуйте цю змінну для вставки в шлях 3-бітного SteamID. 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 встановлені в полі «Додати/замінити шлях» й заміну шляху ввімкнено.

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

Cloud_Unity_Auto-Cloud_Example.png

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

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

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

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


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

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

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

Для докладнішої інформації дивіться документацію ISteamRemoteStorage, особливо ISteamRemoteStorage::RemoteStorageLocalFileChange_t, ISteamRemoteStorage::GetLocalFileChangeCount та ISteamRemoteStorage::GetLocalFileChange.

Дивіться також ISteamRemoteStorage::BeginFileWriteBatch та ISteamRemoteStorage::EndFileWriteBatch — ці оболонки слід використовувати для надання підказок Steam, які допоможуть безпечно синхронізуватися зі Steam Cloud у час, коли користувач ініціює призупинення системи.

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

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

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

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