> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 游戏存档开发者指南

> 将 XBOX GDK 游戏存档集成到标题中，提供有关术语、XGameSave 和 XGameSaveFiles API、用户模型、PLM、安全性和认证的指导。

本指南为将游戏存档功能集成到标题中提供了起点。本文涵盖了必要术语的概述、可用 API 的大纲以及重要的注意事项，如用户模型、安全性和认证要求。

## 概述

以下术语出现在整个游戏存档生态系统中。

* **游戏存档生态系统**：以前称为 *Connected Storage* 或 `XGameSave`，此生态系统管理游戏在设备上保存数据以及将该数据与云同步的方式。该生态系统将保存的数据组织成容器和 blob。这种组织方式帮助标题跨设备存储、更新和检索玩家进度。
* **标题**：你正在开发的游戏。
* **沙盒**：你的标题运行的环境。
* **Microsoft Partner Center**：管理标题配置和沙盒的 Microsoft Web 门户。
* **服务配置标识符 (SCID)：** XBOX services 中标题的服务配置的唯一标识符。
* **Microsoft 帐户 (MSA) 应用 ID (MSAAppID)**：将游戏与其 Microsoft 帐户身份关联的必需标识符。此值在 Partner Center 中生成，并放置在 MicrosoftGame.config 中，以便 XBOX services（包括登录、成就、云存档和用户数据）能够正确对标题进行身份验证。

以下常见服务术语出现在游戏存档 API 中。

* **本地存储**：在游戏过程中保存到设备的数据。
* **游戏存储/云：** 当设备连接到互联网时，存储会自动与云中的游戏存储同步。
* **锁：** 一种在用户当前使用的设备上，为特定用户授予对标题游戏存档独占访问权的机制。锁确保在锁被持有时，没有其他设备可以修改该用户的游戏存档。
  * 例如，如果用户在设备 A 上玩标题 T，则 A 上具有该用户的标题 T 的锁。
* **提供程序：** 与游戏存档系统通信并负责管理游戏数据的中介机制。该提供程序还管理设备上用户的锁。
* **容器**：类似于文件夹。
* **Blob**：类似于单个文件。

## 新标题

在使用游戏存档之前，你的标题必须在 Partner Center 中启用 XBOX services。该服务为你的标题提供一个 SCID 和一个 MSAAppID。有关更多信息，请参阅[为你的标题启用 XBOX services 和游戏存档](https://devdocs.xbox.com/zh-CN/build/core-features/common/game-save/game-saves-walkthroughs-and-samples.md#enabling-xbox-services-and-game-saves-for-your-title)。

在 Partner Center 设置好后，我们建议使用 [XGameSaveFiles](https://devdocs.xbox.com/zh-CN/build/core-features/common/game-save/xgamesavefiles.md) 实现游戏存档。

## 游戏存档 API

| API | 描述 | 平台 | 使用场景 | 示例 |
| - | - | - | - | - |
| [XGameSaveFiles](https://devdocs.xbox.com/zh-CN/build/core-features/common/game-save/xgamesavefiles.md) | 提供一个游戏存档本地存储的文件路径，自动同步到云端。 | PC、XBOX | 我们建议大多数场景使用此 API。为你提供一个可读/写的文件路径，并自动同步到云端。 | [GameSaveFilesCombo](https://learn.microsoft.com/samples/microsoft/xbox-gdk-samples/gamesavefilescombo/) |
| [无代码云存档](https://devdocs.xbox.com/zh-CN/build/core-features/common/game-save/game-saves-walkthroughs-and-samples.md#porting-previous-titles-to-pc-game-saves-with-no-code-cloud-saves) | 你提供一个自动同步到云端的文件路径。 | PC | 适合无法直接使用 GDK 或正在移植到 PC Game Pass 的 PC 游戏。在游戏的 .config 文件中提供读/写路径。 | 无 |
| [XGameSave](https://devdocs.xbox.com/zh-CN/build/core-features/common/game-save/xgamesave.md) | 数据保存在本地并同步到云端。 | PC、XBOX | 支持需要更大或更复杂的每用户存储的标题。提供文件管理的详细控制。 | [GameSaveCombo](https://learn.microsoft.com/samples/microsoft/xbox-gdk-samples/gamesavecombo/) |

## 用户模型

游戏支持两种类型的用户模型。我们建议使用简单用户模型。

| 方法 | 描述 | 示例链接 | 零售平台差异 |
| - | - | - | - |
| 简单用户模型 | 需要一个默认用户。他们控制游戏实例的生命周期。操作系统确保在游戏启动时用户登录。 | [SimpleUserModel](https://learn.microsoft.com/samples/microsoft/xbox-gdk-samples/simpleusermodel/) | PC：默认用户注销时游戏终止。  主机：默认用户注销时游戏挂起。 |
| 高级用户模型 | 没有默认用户。不保证游戏启动时有用户登录。 | 无 | 无 |

有关用户模型的更多信息，请参阅 [GDK 用户模型](https://devdocs.xbox.com/zh-CN/build/core-features/common/user/gamecore-user-models.md)。

有关用户登录最佳实践的信息，请参阅[如何：用户登录的最佳实践](https://devdocs.xbox.com/zh-CN/build/core-features/common/user/xuser_howto_best_practice_signing_in.md)。

## 安全性

### 个人数据

Microsoft 不提供 API 或工具让你访问特定用户的游戏存档数据。如果你需要此信息来排查问题，请直接联系用户并要求其共享。

### 安全保存

启用 PC 辅助功能时，游戏存档不安全。启用 PC 辅助功能后，用户可以直接打开文件路径，从而暴露保存的数据。我们建议你有自己的服务器端检查来确认游戏存档的适当状态。

## 认证要求

### XR-052

[XR-052 用户状态和标题保存位置、漫游和依赖项](https://learn.microsoft.com/build/store/policies/XR/XR052)


## Related topics

- [游戏存档概述](https://devdocs.xbox.com/zh-CN/build/core-features/common/game-save/game-saves-overview.md)
- [游戏存档（目录）](https://devdocs.xbox.com/zh-CN/build/core-features/common/game-save/game-saves-toc.md)
- [游戏存档](https://devdocs.xbox.com/zh-CN/build/core-features/common/game-save/index.md)
- [PC 开发者常见问题](https://devdocs.xbox.com/zh-CN/build/gdk-and-engines/guides/pc-faq.md)
- [游戏存档快速入门](https://devdocs.xbox.com/zh-CN/services/playfab/player-progression/game-saves/quickstart.md)