ISteamRemoteStorage API 方法完成所有读写操作,这些方法会将文件写入本地硬盘上游戏的存储文件夹并同步到云端。也可以选择直接对计算机文件系统进行所有读写操作,然后使用 Steam Auto-Cloud 自动将包含游戏数据的本地文件夹同步到云端。
XBOX Game Development Kit(GDK)支持这两种方法:
- 对于基于代码的云存档,GDK 提供了一个更复杂的
XGameSavesAPI 的简化封装,其功能与ISteamRemoteStorage的方法类似。 - 对于类似 Steam Auto-Cloud 的方式,GDK 支持使用无代码云存档将旧游戏移植到 PC 游戏存档,可将指定的本地文件夹同步到云端,而无需修改文件 I/O 代码。
完整(非封装)的
XGameSaves API 比这个简单封装提供了更多的功能和灵活性。如果你想使用该 API 的任何功能,就不应使用封装,因为游戏绝不应在两者之间切换或混合调用两者的 API。有关 XGameSaves API 的更多信息,请参阅 Game saves。文件操作对比
以下代码示例展示了如何在 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
XBOX Game Development Kit(GDK)
参考文档
Microsoft.Xbox.Wrappers.XGameSave.Provider.Save删除文件
在 Steam 上,你可以只删除云端的文件而保留本地副本(FileForget),也可以同时从两处删除文件(FileDelete)。XGameSave 封装 API 没有与 FileForget 等价的功能。它的 Delete 函数的作用类似于 Steamworks 中的 FileDelete。
Steamworks
XBOX Game Development Kit(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
XBOX Game Development Kit(GDK)
参考文档
- Microsoft.Xbox.Wrappers.XGameSave.Provider.QueryContainers
- Microsoft.Xbox.Wrappers.XGameSave.Provider.QueryContainerBlobs
检查可用空间
在以下示例中,totalBytes 是你的游戏在云存储提供程序中获得的空间大小,而 availableBytes 是剩余的可用空间量(即 availableBytes = totalBytes – bytesUsed)。
Steamworks
XBOX Game Development Kit(GDK)
参考文档
Microsoft.Xbox.Wrappers.XGameSave.Provider.GetQuota术语差异
在 Steam 上,远程存储的数据以文件形式管理,其行为类似于本地硬盘上的文件。读写通过指定要读/写的文件、并获取/设置该文件中所含的字节来完成。 在 XBOX Game Development Kit(GDK)中,与 Steam 文件等价的概念是 blob(数据块),并且 blob 会被分组存放在一个称为 container(容器)的结构中。容器就是一个命名的 blob 分组。例如,可以使用容器为每个用户提供多个存档槽位,在每个槽位中包含同样的文件名。如果你不需要容器提供的这层额外组织结构,只需将所有 blob(文件)放在同一个容器中即可。容器名称不能包含空格。尝试访问或创建
0x80830001:指定的卷不支持存储层。
存储限制
XBOX Game Development Kit(GDK)的单个 blob/文件写入大小和整体存储限制都低于 Steam。在 Steam 上,每次文件写入操作限制为 100 mebibytes(MiB)。每个文件不能超过 200 MiB,而XGameSave API 及其封装则不允许单个 blob 超过 16 MB,并且每位用户每款游戏最多可存储 256 MB。
如果你需要在一个 blob 中存储超过 16 MB 的数据,就需要将数据拆分为多个 blob,并实现一个顺序读/写函数,每次读/写一个 blob。
封装函数是阻塞式的
ISteamRemoteStorage 接口提供两种版本的读写函数:FileRead/FileWrite 和 FileReadAsync/FileWriteAsync。后者为异步函数,会在文件读/写完成后进行回调。简化后的 XGameSave 封装函数并未为其等价于 FileRead/FileWrite 的函数提供异步版本。不过,Provider::Load 和 Provider::Save 都是阻塞式的,因此在你的游戏中使用它们时务必牢记这一点。
出于这个原因,如果在 UI 线程中调用 Provider::Initialize,则会抛出异常。
初始化
在做任何其他事情之前,你需要将封装的头文件包含到你的游戏解决方案中。它位于 %GRDKLatest%\GameKit\Include\xgamesavewrappers.hpp。 在使用XGameSaves 封装的方法之前,你必须创建 Provider 类的实例(你应在游戏的整个生命周期内持有它的指针),并调用 Provider::Initialize 方法。再次强调,该方法应在与 UI 线程分开的线程中调用,如果从 UI 线程调用则会抛出异常。请注意,要初始化封装的提供程序,你需要有当前用户的 XUserHandle 以及你的游戏的服务配置标识符(SCID)。
