游戏存档
XGameSave API 允许在游戏连接到 Internet 时，将游戏数据保存到本地存储区，以便同步到云中。 在同步后所连接的任何其他设备都可以使用保存的数据。 保留的数据的确切粒度因每个游戏而异。 建议你尽可能准确地保存游戏状态以提供最佳恢复体验。
开发者应将游戏保存数据划分为逻辑组，与编写一体式保存相比，逻辑分组可独立更新。 这允许游戏减少在不同情况下写入的数据量，从而减少本地资源消耗量和其他 IO 使用量。 API 还允许游戏在原子操作中更新多个数据项，原子操作或者确保完全成功，或者根本不生效（例如，在保存到一半发生灾难性故障的情况下）。
因为用户可通过 Xbox One 在游戏间快速切换，所以开发者应将其游戏设计为保持当前状态可在预计收到暂停事件时立即保存，Suspend 事件几乎可在任何时间发生。
XGameSave API 使用游戏保留外的 RAM 作为第一存储点，以便在短暂停时间范围内最大化游戏写入速度。 然后，系统将数据存入持久存储，将其与自上次上传后写入的任何其他数据协调。 在存储并进入上传队列后，系统就可以防止网络连接丢失或电源故障等各种失败。
XGameSave API
XGameSave API 提供以下功能。
- 为每个 TitleID/服务配置标识符 (SCID) 的每位用户提供总计 256 MB 的存储容量。
- 在电源出现故障时进行处理。
- 数据将自动同步到云中。
- 可在 Xbox One 设备上提供云支持的数据。
- 平台独立于游戏处理跨设备同步和冲突管理。
- 对于每次调用可上传到 XGameSaveSubmitUpdate（或 XGameSaveSubmitUpdateAsync）的数据量都有 16 MB 的限制。
当游戏达到用户的存储限制时，对 XGameSaveSubmitUpdate 和 XGameSaveSubmitUpdateAsync 的调用将失败。 想要知道还有多少配额可用的游戏可以调用 XGameSaveGetRemainingQuota 或 XGameSaveGetRemainingQuotaAsync。
XGameSave API 提供对异步和同步（阻止）调用的支持，具体取决于你的首选编程模型。 请注意，由于这是 API 执行的 IO，一些调用可能需要任意的时间来运行。 请勿从关键游戏引擎线程调用任何同步 API。 请考虑通过调用 XThreadSetTimeSensitive 来标记关键游戏引擎线程。
为 XGameSave 配置游戏
使用 XGameSave API 时，所有读取和写入操作都与 Xbox 服务主 SCID 相关联。 特定的游戏可能有多个服务配置；每个服务配置都有其自己的 ID。 SCID 是初始化 XGameSave API 所必需的，因而必须传递到 XGameSaveInitializeProviderAsync。
你必须先初始化提供程序，然后再使用 XGameSave API 进行任何其他操作。
跨游戏游戏保存
若要将数据从一个游戏传输或访问到另一个游戏，需要执行两个步骤。
- 修改要在合作伙伴中心访问的游戏的访问策略。
-
XGameSave在源代码中初始化这两个游戏的提供程序。
修改访问策略
游戏可以通过配置访问策略来控制哪些游戏有权访问其 XGameSave 数据。
- 转到合作伙伴中心。
- 选择 “应用和游戏> *你的游戏* >游戏设置”。
- 在 “游戏设置”中，选择“ 访问策略”，然后展开“ 连接存储”。
- 选择“ 添加应用/服务”，然后添加要提供访问权限的游戏。
- 添加完标题后，选择“ 保存”，然后选择“ 发布”。 更改将在一小时内生效。
以下屏幕截图是使“GameSaveFilesCombo”游戏完全可供“GameSaveSample”游戏访问的示例。
初始化 XGameSave 提供程序
现在，你有权访问第一个游戏， XGameSave 可以从另一个游戏读取数据。
- 如果使用
XGameSave，请为每个游戏调用 XGameSaveInitializeProvider/XGameSaveInitializeProviderAsync 。 - 如果使用
XGameSaveFiles，则会隐式初始化提供程序。 为每个游戏调用 XGameSaveFilesGetFolderWithUiAsync 。
XGameSave 概念
为了便于你正确理解 API，下面介绍了一些有用的概念。
- 存储空间：存储空间表示用户的所有保存数据。 默认情况下，每位用户 TitleID/SCID 限制为 256 MB。
- 存储容器：存储空间可由多个存储容器组成。 每个存储容器均可以表示一个为用户保存的游戏或任何其他对游戏有意义的逻辑块。 每个存储容器都有一个名称。
- 存储 blob：每个存储容器都由 blobs 组成。 每个 blob 都有一个名称。 Blob 是组成特定存储容器的数据。
XGameSave 存储空间
在较高层面上，XGameSave 系统中的所有数据都与用户或计算机（例如，一台单独的 Xbox One 主机）关联。 由特定用户或计算机的应用保存的所有数据都存储在 XGameSave 存储空间中。
游戏的每个用户都能获取总存储限制为 256 MB 的 XGameSave 存储空间。 请注意，此存储空间仅用于你的游戏，此存储空间不与其他游戏共享。
要获取存储空间，你的游戏可调用 XGameSaveInitializeProvider 或 XGameSaveInitializeProviderAsync。 如果传入 XUserHandle，则提供程序将自动获取并同步该用户的存储空间。 该空间中的所有容器都将同步，因此这可能是一个长时间运行的操作，尤其是如果用户已经在一台设备上保存数据，并且第一次在其他设备上继续游戏。 完成此操作后，与存储空间的后续交互将不需要云的任何响应即可完成。
初始化提供程序时，游戏可以选择使用“按需同步”。使用此选项时，初始同步仅从云中下载有关容器的必要元数据。 此操作的速度很快，而且在良好的网络条件下，用户可能看不到加载屏幕。 仅在实际访问容器（即读取一个或多个 blob 或执行 blob 查询）时，才会进行完全下载。
由你决定是按需同步还是“一次性”进行同步。 如果游戏保存的数据量较小，或者在同步所有数据时只需要一个点，我们强烈建议不要使用“按需同步”。但是，如果游戏使用量保存，并且用户不需要所有保存数据来玩游戏，则使用“按需同步”可能通过仅在需要时提取数据来显著改善用户体验。
注意
当使用“按需同步”时，如果设备上当前有内容在与云中可能存在的内容争用，每次访问需要同步的容器时，都可能向用户显示各种对话框，如“同步进度”或“冲突”。
有关更多详细信息，请参阅 按需同步 (NDA 主题)要求授权 概述。
XGameSave 容器和 blob
XGameSave 存储容器（或简称容器）是基本的存储单位。 每个 XGameSave 存储空间都可以包含大量容器。
数据会作为一个或多个称为 blob 的缓冲区存储在容器中。 每个容器中都有容器文件，此文件包含对容器中的每个 blob 的数据文件的引用。
此 API 的存储部分旨在轻松地以安全、可靠和事务性的方式将数据从游戏传输到永久性存储器中。 我们希望确保容器的备份数据始终一致。 因此我们希望整个操作自动成功或失败。 我们不希望容器内某些 blob 数据与其他数据不一致的情况下进行部分更新。 为了执行此操作，我们提供 blob 写入和删除提交到的更新上下文。 在其就绪时提交整个上下文。
若要开始对容器进行更新，游戏必须首先通过调用 XGameSaveCreateContainer 获得容器句柄。 然后，游戏必须调用 XGameSaveCreateUpdate 来获取更新上下文。 游戏具有更新的上下文后，就可以对 XGameSaveSubmitBlobWrite 或 XGameSaveSubmitBlobDelete 进行调用。 当游戏准备提交一批更改时，它会调用 XGameSaveSubmitUpdate 或 XGameSaveSubmitUpdateAsync。 更新中描述的所有更改将自动应用。 所有 blob 都将按要求进行更新，否则整个操作将被中止，并且容器仍会处于开始更新之前的状态。 对于每个更新，游戏最多只能有 16 MB 的数据。
注意
XGameSave API 要求你的游戏正确配置其 TitleID 和 SCID 之后才能正常工作。 有关这些所需 ID 的详细信息，请参阅 设置沙盒。 必须在合作伙伴中心中为 Xbox 服务启用您的游戏。
如果你未正确配置 SCID 和游戏 ID，则 XSaveGame API 调用将失败，并出现以下错误代码。
E_GS_NO_ACCESS - 0x80830002 - 操作失败，因为该游戏不具有访问容器存储空间的权限。