Документація 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

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


It is important to remember that Steam will synchronize the user's Steam Cloud files for your game before and after every session. Any matching files which change during the session will be uploaded to Cloud storage immediately afterward. If your game writes very large files, or many small files, to Steam Cloud, then this may cause a noticeable impact on the user's internet bandwidth and also delay their ability to shut down Steam or re-launch the game.

As a general rule, smaller files will work better. If the saved state for a given user can be split up into different categories - things which may change frequently, and things which may not change often - then we recommend using separate files for those categories. That way, the un-changed state will not be re-uploaded after every session.

File Size Limits


The absolute limits on file sizes for Steam Cloud may change over time. Here are some current limits and thresholds:

SizeRestriction
100MBMaximum size for a call to ISteamRemoteStorage::FileWrite or ISteamRemoteStorage:;FileWriteStreamWriteChunk
256MBMay result in a non-optimal storage endpoint choice for the user's location, negatively impacting upload/download performance

Initial Setup

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.

Steam Cloud API and 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 Steamworks API Example Application (SpaceWar) project.

The second is Steam Auto-Cloud.
Steam Auto-Cloud was designed for legacy games where you can not easily integrate the Steam Cloud API. It provides a quick and easy way to get started but lacks the power and flexibility that is available with the Steam Cloud API.

It is generally recommended that you use the Cloud API if possible as it allows for deeper integration and customization, and it enables you to best provide the high quality experience that Steam users have come to expect from the Steam 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 persisted 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 Initial Setup 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/[ім’я_користувача]/[тека_гри]/
    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, то рекомендується використовувати спеціальні значення шляху в полі піддиректорії.

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 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.

Cloud_Unity_Auto-Cloud_Example.png

Pre-release Testing

If you are adding Steam Auto-Cloud to a game which is already released and you have enabled developer-only mode during the Initial Setup then you must complete some additional steps to test the functionality.
  1. Увійдіть у Steam з акаунта, що має ліцензію Developer Comp для застосунку, який ви тестуєте.
  2. Відкрийте консоль Steam переходом до steam://open/console у вашому веб-оглядачі.
  3. Введіть у консолі testappcloudpaths <AppId> з AppID застосунку, який ви тестуєте. Приклад: testappcloudpaths 480
  4. Введіть у консолі set_spew_level 4 4.
  5. Запустіть ваш застосунок у Steam.
  6. Якщо в теках хмарної автосинхронізації вже наявні файли, то в консолі ви побачите їхнє вивантаження. Якщо ні, то збережіть кілька файлів цього застосунку й потім закрийте його, щоби запустити синхронізацію.
  7. Перейдіть на інший ПК і повторіть кроки вище, щоби перевірити як працює завантаження файлів автосинхронізації.
  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.

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 Debugging the Steamworks API for additional information.