Steamworks 文獻庫
Steam 雲端服務
簡介
Steam 雲端會自動將遊戲中的檔案儲存至 Steam 伺服器,玩家無論從哪一台電腦登入 Steam,都能取用遊戲存檔。
整合層級
您需要在 Steamworks 網站上設定檔案路徑。 您也可以選擇在遊戲程式碼中使用某些 API 呼叫 Steamworks 來進行上傳、下載、列舉和刪除。

Steam 雲端服務概覽

Steam 雲端為您的遊戲提供一個簡單透明的遠端檔案儲存系統。 在自動雲端配置中指定的檔案或使用雲端 API 寫入(建立、修改、刪除等)磁碟的檔案,將在遊戲關閉後自動複製到 Steam 伺服器上。

如果使用者換了一台電腦,在遊戲啟動之前,檔案會自動下載到新電腦上。 然後,遊戲可透過雲端 API 讀取檔案,或像往常一樣直接從磁碟讀取檔案。 請避開影片設定等針對個別電腦的配置。

Steam 用戶端會確保在使用者可能使用的所有電腦上,檔案都能保持同步。

使用者可以在 Steam 雲端設定下透過取消勾選「為支援的應用程式啟用 Steam 雲端同步功能」來全面停用雲端同步。

使用者還可以在各別遊戲的屬性中選擇性地停用雲端同步。

Spacewar_Cloud_Properties.png

備註和最佳作法


有一點很重要,Steam 會在每個工作階段前後,為您的遊戲的使用者 Steam 雲端檔案進行同步。 任何相符檔案只要在工作階段期間有所變更,都會在變更發生後立即上傳到雲端儲存空間。 要是遊戲將非常龐大的檔案或許多小檔案寫入 Steam 雲端,可能會明顯影響使用者的網路頻寬,使得關閉 Steam 或重新啟動遊戲的速度變慢。

較小的檔案通常處理起來比較流暢。 如果某個使用者的儲存狀態可以分為常變動和不常變動這兩類,我們建議可以按照這些特性,將檔案拆成數個。 這樣可以省得在每個工作階段之後,又重新上傳未變更的狀態。

檔案大小限制


Steam 雲端的絕對檔案大小限制可能會隨著時間改變。 下面是現行的限制和門檻值:

大小限制
100MBMaximum size for a call to ISteamRemoteStorage::FileWrite or ISteamRemoteStorage::FileWriteStreamWriteChunk
256MB可能導致使用者位置的儲存點選擇不理想,拖累上傳 / 下載性能

初始設定

要設定 Steam 雲端,您必須在 Steamworks 應用程式管理員面版的 Steam 雲端服務設定頁面上,設定每位使用者的位元組配額每位使用者的檔案數量選項。

這個配額將強制施加於每款啟用雲端的遊戲,以每位使用者的每款遊戲為準。 建議您為自己的遊戲設定一個合理的配額。

備註: 設定完畢後,記得按下頁底的「儲存」按鈕,發佈所更新的設定。 發佈之後,雲端圖示便會出現在該遊戲擁有者的 Steam 用戶端中。

若您的遊戲已經公開發行,可以勾選標示為啟用雲端支援(限開發者)的方塊。 啟用限開發者模式後,只有擁有您產品的「Developer Comp」授權的 Steam 帳戶才會看見雲端圖示,得以使用 Steam 雲端服務。 您可以利用這一點,在不影響公開使用者體驗的情況下,安心測試 Steam 雲端整合功能。 未發行的遊戲不會受到任何影響,既然還無人擁有該遊戲,也沒人能看見或存取任何特定 App ID 的雲端儲存內容。

填寫共用的雲端 App ID 欄位之後,您就能在兩個 App ID 之間共享雲端儲存空間。 這種做法最常用於共享試用版與完整版的遊戲存檔。 將值設定為 0 則可停用此功能。

Steam 雲端 API 和 Steam 自動雲端

Steam 上有兩種利用 Steam 雲端的方式,請閱讀下文了解這兩者之間的不同,再判斷哪種方法較適合您的應用程式。

第一種方式是 Steam 雲端 API。
雲端 API 提供了一系列的功能,方便您直接將 Steam 雲端整合到自己的遊戲中。 雲端 API 分開處理每個 Steam 使用者檔案,有助於更深入控制 Steam 雲端。

Steam 雲端 API 可透過 ISteamRemoteStorage API 介面存取,您可以在 Steamworks API 範例應用程式(SpaceWar)一文中找到範例用法。

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

If you prefer a deeper integration with Steam Cloud (for example, allowing to choose which save files are stored in the cloud), then you should use the Cloud API. Otherwise you can use Steam Auto-Cloud.

Steam 自動雲端

自動雲端為 Steam 雲端 API 的替代方案,允許應用程式存取 Steam 雲端,省去任何自己寫程式或修改遊戲的麻煩。 您只需指定想持續保存在雲端的檔案組。 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 Install]\SteamApps\common\[Game Folder]\
    SteamCloudDocuments所有平台特定路徑,Linux 平台的例子:~/.SteamCloud/[username]/[Game Folder]/
    WinMyDocumentsWindows%USERPROFILE%\My Documents\
    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} - 在 Steam 路徑中使用此變數,插入使用者的 64 位元 Steam ID。 64 位元的 Steam ID 範例:76561198027391269
    • {Steam3AccountID} - 在 Steam 路徑中使用此變數,插入使用者的 3 位元 Steam ID。 Account ID 的範例:67125541
    範例:SavesDir/{64BitSteamID}
  3. 模式

    應相符的檔案遮罩模式。 您可使用 * 作為萬用字元。 如果您希望目錄中包括所有檔案,只需使用 *

    範例:*.sav
  4. 作業系統

    設定這些檔案的來源和將同步至的作業系統。 這個步驟只有在檔案僅適用於特定作業系統時才有必要,希望這種情況不會發生!
  5. 遞迴

    搜尋相符的檔案時包含子目錄。 在處理名稱不具判別性(如名稱不為 Steam 使用者名稱或 ID)的子目錄時,此設定很有幫助。 如果使用 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. 替換路徑

    一旦啟用,將導致在新增或替換路徑中指定的路徑完全取代原始子目錄。

範例:為 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://open/console 以開啟 Steam 主控台
  3. 在主控台中輸入 testappcloudpaths 以及您正在測試的應用程式的特定 App ID, 例如:testappcloudpaths 480
  4. 在主控台中輸入 set_spew_level 4 4
  5. 從 Steam 啟動您的應用程式
  6. 檢查主控台活動,如果檔案已經存在於自動雲端路徑中,那麼您應該可以看到這些檔案被上傳。 否則,從您的應用程式中儲存一些檔案,然後關閉此應用程式來觸發同步
  7. 換另一台電腦重複以上步驟,測試從 Steam 自動雲端下載檔案
  8. 務必在所有支援的作業系統上進行測試
  9. 設定 testcloudapppaths 0set_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 Debugging the Steamworks API for additional information.