ISteamRemoteStorage API 方法進行所有讀取和寫入,這些方法會將檔案寫入本機硬碟上遊戲的儲存資料夾,並將它們同步到雲端。或者,您可以直接對電腦的檔案系統進行所有讀取和寫入,然後使用 Steam Auto-Cloud 將包含遊戲資料的本機資料夾同步到雲端。
Microsoft Game Development Kit (GDK) 支援這兩種方法:
- 對於以程式碼為基礎的雲端存檔,GDK 提供較複雜之
XGameSaveAPI 的簡化包裝函式,提供與ISteamRemoteStorage方法類似的功能。 - 對於類似 Steam Auto-Cloud 的方法,GDK 支援使用無程式碼雲端存檔將舊版遊戲移植到 PC 遊戲存檔,可將指定的本機資料夾同步到雲端,而不需要變更您的檔案 I/O 程式碼。
完整、未包裝的
XGameSave API 比簡單的包裝函式提供更多功能和彈性。如果您需要其中任何功能,請勿使用包裝函式。遊戲不得在兩者之間切換,也不得混用兩者的 API 呼叫。如需 XGameSave API 的詳細資訊,請參閱遊戲存檔。檔案作業比較
下列程式碼範例示範如何在 Steamworks Remote Storage API 和 GDK 對等項目中完成基本檔案作業。這些範例假設provider 變數保存指向已初始化之 Microsoft::Xbox::Wrappers::GameSave::Provider 物件的指標。
如果您不是使用 Steam Remote Storage API,而是選擇使用 Steam Auto-Cloud,請將 Remote Storage API 呼叫取代為其對等的檔案系統 API。
讀取檔案
Steamworks
GDK
參考文件
Microsoft.Xbox.Wrappers.XGameSave.Provider.Load寫入檔案
Steamworks
GDK
參考文件
Microsoft.Xbox.Wrappers.XGameSave.Provider.Save刪除檔案
在 Steam 上,您可以刪除雲端中的檔案但保留本機複本 (FileForget),或從兩個位置刪除檔案 (FileDelete)。XGameSave 包裝函式 API 沒有與 FileForget 對等的項目。它的 Delete 函式運作方式與 Steamworks 中的 FileDelete 相同。
Steamworks
GDK
參考文件
- Microsoft.Xbox.Wrappers.XGameSave.Provider.Delete(std::string)
- Microsoft.Xbox.Wrappers.XGameSave.Provider.Delete(std::string, std::string)
- Microsoft.Xbox.Wrappers.XGameSave.Provider.Delete(std::string, BlobNames)
取得所有檔案
Steamworks
GDK
參考文件
- Microsoft.Xbox.Wrappers.XGameSave.Provider.QueryContainers
- Microsoft.Xbox.Wrappers.XGameSave.Provider.QueryContainerBlobs
檢查可用空間
在下列範例中,totalBytes 是雲端儲存提供者提供給您遊戲的空間量。availableBytes 是剩餘的可用空間量(也就是 availableBytes = totalBytes – bytesUsed)。
Steamworks
GDK
參考文件
Microsoft.Xbox.Wrappers.XGameSave.Provider.GetQuota術語差異
在 Steam 上,遠端儲存資料是以檔案的形式管理,運作方式就像本機硬碟上的檔案。若要讀取或寫入,您需要指定檔案,然後取得或設定其所包含的位元組。 在 Microsoft Game Development Kit (GDK) 中,與 Steam 檔案對等的是_blob_。Blob 會群組在稱為_容器_的結構中。容器是具名的 blob 群組。例如,您可以使用容器來支援每位使用者多個存檔位置,每個位置中使用相同的檔案名稱。如果您不需要容器所提供的額外組織層,請將所有 blob(檔案)放在同一個容器中。容器名稱不能包含空格。嘗試存取或建立包含空格的容器名稱,會導致提供者方法傳回
0x80830001 的 HRESULT:指定的磁碟區不支援儲存層。儲存限制
Microsoft Game Development Kit (GDK) 的 blob 或檔案寫入大小上限及整體儲存限制都比 Steam 低。在 Steam 上,每個檔案寫入作業限制為 100 mebibyte (MiB),且每個檔案不能大於 200 MiB。相較之下,XGameSave API 及其包裝函式將每個 blob 限制為 16 MB,且每位使用者每個遊戲最多允許 256 MB。
如果您需要在一個 blob 中儲存超過 16 MB 的資料,請將資料分割成多個 blob。然後實作循序讀取和寫入函式,一次處理一個 blob 的資料。
包裝函式會造成封鎖
ISteamRemoteStorage 介面提供兩種版本的讀取和寫入函式:FileRead 和 FileWrite,以及 FileReadAsync 和 FileWriteAsync。Async 版本會在檔案讀取或寫入完成時回呼。簡化的 XGameSave 包裝函式並未提供其 FileRead 和 FileWrite 對等項目的非同步版本。Provider::Load 和 Provider::Save 都會造成封鎖,因此在遊戲中使用它們時請記住此行為。
因此,如果您從 UI 執行緒呼叫 Provider::Initialize,它會擲回例外狀況。
初始化
在使用任何包裝函式方法之前,請在遊戲的方案中包含包裝函式的標頭檔。您可以在 %GRDKLatest%\GameKit\Include\xgamesavewrappers.hpp 找到它。 在使用XGameSave 包裝函式的方法之前,請建立 Provider 類別的執行個體,並呼叫 Provider::Initialize 方法。在遊戲的整個生命週期中保存指向 Provider 執行個體的指標。請從 UI 執行緒以外的執行緒呼叫 Provider::Initialize。如果您從 UI 執行緒呼叫此方法,它會擲回例外狀況。若要初始化包裝函式提供者,您需要目前使用者的 XUserHandle 和遊戲的服務設定識別碼 (SCID)。
