Steam 雲端服務概覽

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

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

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

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

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

備註和最佳作法

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

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

檔案大小限制

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

大小	限制
100MB	對 ISteamRemoteStorage::FileWrite 或 ISteamRemoteStorage:;FileWriteStreamWriteChunk 呼叫的檔案尺寸上限
256MB	可能導致使用者位置的儲存點選擇不理想，拖累上傳 / 下載性能

存檔路徑

在決定寫入存檔的位置時，請確保路徑對目前的 Steam 使用者是獨特的。 如有需要，您可以透過 ISteamUser::GetSteamID 取得使用者獨特的 Steam ID， 接著從 GetAccountID() 取得其帳戶 ID，如此一來就能使用獨特的變數來建立存檔路徑。

跨平台存檔

如果您的遊戲支援多個平台——或僅是計畫未來再支援——那麼在為您的遊戲設置 Steam 雲端服務時，都應該將這點納入考量。

如果您打算直接透過 ISteamRemoteStorage 介面來讀取或寫入檔案，那麼可以透過 ISteamRemoteStorage::SetSyncPlatforms 控制平台間的同步。 預設狀態下，新檔案會同步給所有平台。

如果您打算使用 Steam 自動雲端，請務必了解以下關鍵事項。 首先，新檔案預設只會同步至相關自動雲端根路徑的作業系統設定。 這表示如果您為每種作業系統設定不同的根，則所有檔案將照平台分隔，也就不會有跨平台存檔功能。

若要啟用跨平台存檔，應改為定義一個單一的根路徑（通常為 Windows），然後為支援的平台建立根覆寫。 符合指定根路徑並擁有平台根覆寫的檔案，將同步至原始的根與所有覆寫的每一個平台。 詳情請見 Steam 自動雲端。

初始設定

要設定 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 Example Application (SpaceWar)一文中找到範例用法。

第二種方法是 Steam 自動雲端。
Steam 自動雲端是為您選擇不整合 Steam 雲端 API 的遊戲所設計。 它的初步設定快速簡單，但缺乏 Steam 雲端 API 的靈活性。

如果您希望更深入地整合 Steam 雲端（例如可以選擇將哪些存檔儲存於雲端中），則應使用雲端 API。 若不需要，則可以使用 Steam 自動雲端。

Steam 自動雲端

自動雲端為 Steam 雲端 API 的替代方案，允許應用程式存取 Steam 雲端，省去任何自己寫程式或修改遊戲的麻煩。 您只需指定想持續保存在雲端的檔案組， Steam 就會在應用程式啟動和退出時自動同步檔案組。 請避開影像品質等針對個別電腦的配置。

初步設定

完成初始設定後，Steam 雲端服務設定下就會出現「Steam 自動雲端設定」。

根路徑會用來指定將持續保存在 Steam 雲端的檔案組。 根路徑可以只選定單獨一個檔案，也可以總括指定子資料夾中的所有檔案。 每組要同步的檔案都應使用新的路徑。

根路徑由 5 個部分組成：

1. 根

   這是一個預先確定的路徑列表，遊戲儲存通常位於此處。
   

   根	支援的作業系統	相應路徑
   應用程式安裝目錄	所有	[Steam Install]\SteamApps\common\[Game Folder]\
   SteamCloudDocuments	所有	平台特定路徑，Linux 平台的例子：~/.SteamCloud/[username]/[Game Folder]/
   WinMyDocuments	Windows	%USERPROFILE%\My Documents\
   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/

   
   關於 Windows %USERPROFILE% 路徑的備註：上方列出的相應路徑是預設位置。 現在使用者在安裝 Windows 時，可以設定讓這些資料夾位於不同的位置（不一定在 %USERPROFILE% 中）。 無論這些資料夾的位置是預設還是自訂，Steam 都會使用必要的 Windows API 找到其目前位置。
   
   

2. 子目錄

   與根相關的雲端檔案的子目錄路徑。 如子目錄不存在，請使用「.」。
   
   自動雲端特殊路徑值
   自動雲端允許在子目錄路徑中使用獨特的 Steam 使用者識別碼。 如此您便可以為電腦中的每位 Steam 使用者分別儲存檔案。 您可也以在自己的遊戲中使用 ISteamUser::GetSteamID 獲取目前使用者的 SteamID 或 AccountID 用於儲存和讀取。
   
   • {64BitSteamID} - 在 Steam 路徑中使用此變數，插入使用者的 64 位元 Steam ID。 64 位元的 Steam ID 範例：76561198027391269
     
   • {Steam3AccountID} - 在 Steam 路徑中使用此變數，插入使用者的 Steam3 ID。 Account ID 的範例：67125541
     
   範例：SavesDir/{64BitSteamID}
   

3. 模式

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

4. 作業系統

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

5. 遞迴

   搜尋相符的檔案時包含子目錄。 在處理名稱不具判別性（如名稱不為 Steam 使用者名稱或 ID）的子目錄時，此設定很有幫助。 如果使用 Steam ID，我們強烈推薦在子目錄欄位中使用特殊路徑值。

根覆寫

如果您的應用程式是跨平台的，而且每個作業系統需要不同的目錄，您可以使用根覆寫功能，為您在上方設定的「根路徑」指定覆寫。

上方指定的根路徑可以被覆寫，以對應其它作業系統上的不同路徑。 如果您想使用「根覆寫」，則必須在上方的根作業系統下拉選單中選擇「所有作業系統」。

根路徑覆寫由 5 個部分組成：

1. 原始根目錄

   對應於您上面設置的根之一。
   

2. 作業系統

   執行覆寫的目標作業系統。
   

3. 新根

   原始根對應到指定作業系統中的新位置。
   

4. 新增 / 替換路徑

   您可以選擇性地添加插入新根和原始子目錄之間的子目錄路徑。
   

5. 替換路徑

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

範例：為 Unity 應用程式設定自動雲端功能

以下是設定自動雲端以與 Unity 共同運作的範例，而 Application.persistentDataPath 屬性在每種作業系統上的值都不相同。 根路徑採用 Windows 版本，Unity 中的公司設為 DefaultCompany，專案則稱作 AutocloudSample。 macOS 和 Linux / SteamOS 的 Application.persistentDataPath 替用路徑會在新增 / 替換路徑欄位中設定，並勾選啟用替換路徑。

完成設定後，自動雲端檔案就會在這三個資料夾間同步，如預覽範例所示：

發行前測試

如果要為已發行的遊戲加入 Steam 自動雲端，並且在%20#initial-setup期間啟用了僅限開發者模式，則必須進行一些額外步驟來測試功能。

1. 以擁有欲測試遊戲的帳戶登入 Steam
   
2. 使用瀏覽器打開 steam://open/console 以開啟 Steam 主控台
   
3. 在主控台中輸入 testappcloudpaths<AppId> 以及您正在測試的應用程式的特定 App ID， 例如：testappcloudpaths 480
   
4. 在主控台中輸入 set_spew_level 4 4
   
5. 從 Steam 啟動您的應用程式
   
6. 檢查主控台活動，如果檔案已經存在於自動雲端路徑中，那麼您應該可以看到這些檔案被上傳。 否則，從您的應用程式中儲存一些檔案，然後關閉此應用程式來觸發同步
   
7. 換另一台電腦重複以上步驟，測試從 Steam 自動雲端下載檔案
   
8. 務必在所有支援的作業系統上進行測試
   
9. 設定 testappcloudpaths 0 和 set_spew_level 0 0 以結束測試。 您可重新啟動 Steam 用戶端以刪除主控台分頁

完成測試後，別忘了關閉僅限開發者模式，並發佈變更。

動態雲端同步

Steam Cloud 現在支援動態同步功能，可於應用程式工作階段將出現在雲端中的變更下載到本機電腦。 目前的範例是 Steam Deck 上一個暫停的遊戲階段。 Steam 會在階段暫停時，為標記為支援動態雲端同步的應用程式，將檔案同步至 Steam 雲端。 接著，使用者在開啟另一台裝置時，就可以收到來自 Steam Deck 遊戲階段的更新，然後繼續進行遊戲。 結束時，這些變更都會被上傳至 Steam 雲端。 最後，當 Steam Deck 裝置被喚醒時，Steam 會將變更同步到該裝置，並向應用程式發出通知，告知本機檔案已變更。 應用程式接下來可以逐一查看這些變更，然後採取相應動作。 舉例來說，遊戲可以簡單地從磁碟載入更新後的進度，然後讓使用者從剛才在另一部裝置上離開的位置繼續遊戲。

進一步資訊請見我們的公告文章，了解這項功能存在的原因，以及使用方法。

請注意，無論應用程式是使用 ISteamRemoteStorage API 來管理檔案，還是使用自動雲端，都可以支援此功能。

更多詳情請見 ISteamRemoteStorage 文獻，尤其是 ISteamRemoteStorage::RemoteStorageLocalFileChange_t、ISteamRemoteStorage::GetLocalFileChangeCount 和 ISteamRemoteStorage::GetLocalFileChange 的部分。

另外也請見 ISteamRemoteStorage::BeginFileWriteBatch 和 ISteamRemoteStorage::EndFileWriteBatch——這些包裝函式應用來向 Steam 發出提示，以在使用者開始暫停系統時，幫忙安全地同步至 Steam 雲端。

發行前測試

您可以為應用程式在本機啟用動態雲端同步，來測試您的組建——建議您對已發行的遊戲這麼做，因為如果為所有使用者啟用動態雲端同步，但組建無法處理新 API 方法和回呼時，可能會造成使用者的資料丟失。

若希望在電腦本機上測試：

1. 以擁有欲測試遊戲的帳戶登入 Steam
   
2. 使用瀏覽器打開 steam://open/console 以開啟 Steam 主控台 （也可以用 steam -console 命令列執行 Steam，然後直接前往主控台區塊）
   
3. 在主控台中輸入 @cloud_testdynamicsyncapp <AppId>，其中套入欲測試的 App ID。 例如：@cloud_testdynamicsyncapp 480
   
4. 從 Steam 啟動您的應用程式
   
5. 進行遊戲至希望的進度
   
6. 在 Steam 主控台中，輸入 prepare_for_suspend。 Steam 將暫停您的遊戲程序，並將有變更的檔案上傳至 Steam 雲端
   
7. 可選擇進行：在另一台裝置上進行遊戲，將進度推至更後面，然後退出，讓 Steam 用戶端將進度上傳至 Steam 雲端
   
8. 回到原本的裝置，在 Steam 主控台中輸入 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 雲端出現問題，請檢查位於 %Steam Install%\logs\cloud_log.txt 的記錄檔。

相關額外資訊請見 Debugging the Steamworks API。