通过

将 Win32 文件 IO 与游戏保存结合使用 (XGameSaveFiles)

  • 项目

XGameSaveFiles 为主机、电脑和 xCloud 上的云保存提供了替代解决方案。 通过使用 XGameSaveFiles，开发人员可以在其保存系统中使用正常的 Win32 文件 IO 功能，例如 CreateFile 和 WriteFile。

将 XGameSaveFiles 与 XGameSave 进行比较

下表显示了 XGameSaveFiles 和 XGameSave 之间的差异

功能 XGameSaveFiles XGameSave
支持 Win32 文件 IO API 是 否
支持批处理更新 否 是
更新在玩游戏时上传 否 是
支持按需同步 否 是
Xbox/xCloud 上的跨 VM 写入 否 是
初始化 API XGameSaveFilesGetFolderWithUiAsync XGameSaveInitalizeProviderAsync
每个用户的默认存储限制 256 MB 256 MB
文件大小限制 64 MB* 16 MB

* 如果游戏需要支持 XGameSaveFiles 和 XGameSave 之间的互操作，则游戏需要将其文件大小限制为 16 MB。

游戏不能将 XGameSaveFiles 与 XGameSave 混合使用。 游戏必须选择要使用的云存储系统。 如果游戏使用 XGameSaveFiles，并在以后调用 XGameSaveInitializeProvider，则会出现 E_GS_PROVIDER_MISMATCH 错误。 同样，如果游戏使用的是 XGameSave，并在以后调用 XGameSaveFilesGetFolderWithUiAsync，则也会出现 E_GS_PROVIDER_MISMATCH 错误。

在使用 XGameSaveFiles 和 XGameSave 之间进行选择

XGameSave 和 XGameSaveFiles 都提供了一个保存系统，允许在主机、电脑和 xCloud 之间共享云保存。

除了上表中突出显示的差异之外，XGameSave 还提供了最可靠的解决方案，开发人员可以轻松地批处理其写入，并确保这些写入作为原子操作进行。 XGameSaveFiles 对于那些已经在电脑上拥有 Win32 风格的保存系统，并希望将该解决方案移植到适用电脑 Game Pass 的游戏时把成本降到最低的开发者来说是最理想的。

使用 XGameSaveFiles 上传更新时

保存游戏的更新不是游戏的责任，系统会在游戏没有处于“活动”状态时自动处理。 对于不同的平台，没有处于“活动”状态有不同的含义。

对于主机或 xCloud，没有处于“活动”状态意味着：

  • 游戏已暂停
  • 游戏已终止
  • 保存被跟踪的用户已注销

对于电脑，没有处于“活动”状态意味着：

  • 游戏已终止
  • 保存被跟踪的用户已注销
  • 电脑上的电源状态更改
  • 30 分钟后，游戏处于后台或游戏未向 XGameSaveFiles 进行任何新写入

使用 XGameSaveFiles

为了使用 XGameSaveFiles，开发人员必须调用 XGameSaveFilesGetFolderWithUiAsync，为要管理其保存的用户传入 XUser 图柄，并为游戏传入 SCID（Xbox 服务配置 ID）。 当开发人员随后调用 XGameSaveFilesGetFolderWithUiResult 时，他们将获取可用于游戏保存的文件夹，使用标准 Win32 文件 IO API（如 CreateFile、WriteFile 等）读取和写入该文件夹...

恢复游戏后，开发人员应调用 XGameSaveFilesGetFolderWithUiAsync 以确保保存数据完全是最新的。

开发人员需要注意，Win32 文件 IO API 将返回以下错误：

错误 XGameSaveFiles 上下文中的说明
STATUS_NAME_TOO_LONG 目录名称太长
STATUS_OBJECT_NAME_INVALID 目录名称中包含的字符在云服务中无效
STATUS_NAME_TOO_LONG 文件名（忽略目录）太长
STATUS_FILE_TOO_LARGE 文件大小已超过 64 MB
STATUS_FILE_TOO_LARGE 游戏已超出针对游戏保存的每用户最大配额
STATUS_INSUFFICIENT_RESOURCES 游戏已超出它在设备上分配的存储空间

想要了解每用户配额剩余多少的开发人员可以调用 XGameSaveFilesGetRemainingQuota。

XGameSaveFiles 的目录和文件名限制

尽管 XGameSaveFiles 向开发人员隐藏了云保存系统的大多数详细信息，但存在目录和文件名限制，因为这些限制由 Azure Blob 存储支持。 概括而言，完整目录路径将映射到容器，文件名将映射到 Blob。 请考虑以下游戏可能用于保存内容的示例：

[ROOT]/Save1/BraveNewWorld/state001.dat
  • “[ROOT]”是将由 XGameSaveFilesGetFolderWithUiAsync 返回的内容。
  • “[ROOT]”之后的内容一直到最后的左斜杠(含)将映射到容器。
    • 容器名称只能是大写字母 (A-Z)、小写字母 (a-z)、数字 (0-9)、下划线 (_)、句点 (.)、连字符 (-) 和正斜杠 (/)
    • 容器名称上限为 256 个字符
    • 容器名称不能以句点结尾、不能包含两个连续句点，也不能以句点或连字符开头。
  • 最后一个正斜杠（文件名）后的所有内容都将映射到 Blob
    • 文件名的上限为 65 个字符，但可以是 NTFS 中支持的 Unicode 字符
  • 包含文件名(但不包含“[ROOT]”)的完整生成路径必须小于 MAX_PATH(260 个字符)

XGameSaveFiles 开发工具

XGameSaveFiles 使用与 XGameSave 相同的开发工具。 虽然 API 不同，但它们利用完全相同的 XGameSave 存储空间和数据。 以下工具将帮助你开发 XGameSaveFiles。

  • xbstorage
  • xgamesaveutil
  • Fiddler

在主机上使用 xbstorage 管理 XGameSave 数据

Xbstorage.exe 是一种开发工具，可在开发电脑的 Xbox 开发工具包上管理本地 XGameSave 数据。

此工具允许从硬盘上清除本地 XGameSave 存储空间，以及通过使用 .xml 文件导入和导出个人用户连接或计算机连接的存储空间。

在本地 XGameSave 存储空间执行操作时，系统的行为就像由应用本身执行操作一样。 将数据从 XGameSave 存储空间复制到本地文件会导致在复制之前与云进行同步。

同样，将开发电脑上 .xml 文件中的数据复制到 Xbox One 开发工具包上的 XGameSave 存储容器会导致主机开始将此数据上传到云。 存在以下例外：开发工具包无法获取锁定，或者主机中的容器和云中的容器之间存在冲突。 在这种情况下，主机的行为就像用户已经决定不解决冲突一样（例如，通过选取一个要保留的容器版本），且主机的行为就像它在脱机运行，直到下次启动游戏一样。

xbstorage reset 命令会清除所有服务配置标识符 (SCID) 和用户已保存数据的本地存储，但不会改变在云中存储的数据。 如果用户漫游到主机，并在运行游戏时从云中下载数据，那么，这对将主机设置为它应该所处的状态非常有用。

有关 xbstorage.exe 的详细信息，请参阅在主机上管理 XGameSave 数据(xbstorage.exe) (NDA 主题)。

在电脑上使用 xgamesaveutil 管理 XGameSave 数据

Xgamesaveutil.exe 是一种开发工具，可用于管理电脑上运行的游戏的本地 XGameSave 数据。 它的功能与用于管理主机上保存的 xbstorage 工具相同。

有关 xgamesaveutil.exe 的详细信息，请参阅在电脑上管理 XGameSave 数据 (xgamesaveutil.exe)。

使用 Fiddler 监视 XGameSave 网络活动

它可能有助于确定，当执行云存储操作时，设备是否与服务交互。 使用 Fiddler 有助于确定设备是否成功调用服务，或者它是否遇到授权错误。

有关在主机上设置 Fiddler 的信息，请参阅如何将 Fiddler 用于 Xbox 主机。

有关在电脑上设置 Fiddler 的信息，请参阅 Windows 电脑上的 Fiddler。

XGameSaveFiles 和 XGameSave 与连接存储之间的互操作

虽然 XGameSave 和连接存储能够轻松地在它们之间共享保存状态，而无需任何游戏编写的代码，但尝试将这些相同的保存移动到利用 XGameSaveFiles 的游戏时，并不完全是这样。 虽然这可能不是常见场景，但在某些情况下，游戏可能希望与 XGameSaveFiles 互操作。 典型原因可能是：

  • 发布者在主机上已有一个已使用连接存储或 XGameSave 的游戏
  • 发布者不希望更新现有游戏以使用 XGameSaveFiles
  • 发布者认为将 XGameSaveFiles 添加到其电脑游戏比添加 XGameSave 更容易，但仍希望支持电脑和主机与 xCloud 之间的交叉保存进度

在 XGameSave 和 XGameSaveFiles 之间移动相当简单。 当游戏调用 XGameSaveFilesGetFolderWithUiAsync 时，将使用以下规则将容器和 blob 映射到目录和文件：

  • 容器名称中的任何正斜杠 (L'/') 将用于创建文件将驻留在其中的目录结构
  • 以下字符对于 XGameSaveFiles 无效，如果遇到，则会映射到下划线 (L'_')
    • 从 L'\0' 到 L'\001f' 的所有字符，包含两端
  • 以下字符对于 XGameSaveFiles 无效，如果遇到，则会映射到句点 (L'.')
    • 双引号 (L'"')
    • 小于 (L'<)
    • 大于 (L'>')
    • 竖杠符号 (L'|')
    • 星号 (L'*')
    • 问号 (L'?')
    • 反斜杠 (L'\')
  • Blob 名称中的任何正斜杠 (L'/') 都将映射到文件名中的句点 (L'.')

从 XGameSaveFiles 移动回 XGameSave 时，将还原原始容器和 blob 名称，前提是文件名未更改或移动。

另请参阅

XGameSaveFiles 参考