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

# XR-112 激活和恢复时的用户与控制器设置

> XR-112 要求游戏在初始激活和恢复时，使用 GDK 简化用户模型或高级用户模型建立活动用户和控制器。

版本 2.0，2025/11/1

游戏必须建立一个或多个活动用户作为游戏中的主要用户，并在从挂起、睡眠或休眠状态恢复时处理这些用户。在 GDK 中，游戏通过使用简化用户模型或高级用户模型来实现这一点。

**使用 GDK 简化用户模型的游戏**

GDK 中的简化用户模型会代表游戏处理默认用户的获取。游戏仍负责确保为用户分配控制器，并使用该控制器进行游戏输入。如果没有为默认用户分配控制器，游戏应使用 XUserFindControllerForUserWithUiAsync 调出系统对话框来选择控制器，并开始接受玩家的输入。

**GDK 高级用户模型**

在初始激活时，游戏可以根据其游戏设计和偏好来选择如何确定初始用户：使用启动游戏的用户，或者明确提示选择用户。

在对用户的个人资料执行第一个与个人资料相关的操作（例如保存进度或设置）之前，游戏必须指明活动用户。

所有使用高级用户模型的 Microsoft Game Development Kit (GDK) 游戏都必须提供账户选择器的入口点，以便更改活动用户。

当游戏从挂起、睡眠或休眠状态恢复时，游戏必须验证用户/控制器配对，并做出相应反应：恢复先前用户的会话，或者获取一个或多个新用户。

## 更多信息

**在初始激活期间建立用户**

*GDK 简化用户模型*

初始用户通过调用 XUserAddAsync(silent) 提供给游戏，并且始终为启动游戏的用户返回单个结果。

*GDK 高级用户模型、ERA 和 UWP 多用户应用程序*

*如果游戏使用启动游戏的用户：*

* 对于 GDK，可以通过调用 XUserAddAsync(silent) 来确定活动用户。如果系统返回不存在默认用户，游戏必须使用不带 silent 选项的 XUserAddAsync 提示选择用户。这将为用户显示账户选择器。

* 对于 ERA 和 UWP，可以从应用激活上下文的推荐用户 (CoreApplicationContext.CurrentUser) 中找到活动用户。如果应用激活上下文未提供推荐用户，而游戏执行与个人资料相关的操作，则游戏必须启动账户选择器，并根据用户选择的个人资料设置活动用户。

*如果提示选择用户：*

* 游戏显示参与提示，并且必须显示账户选择器。用户根据所做的选择来确定。

* 对于 GDK，使用 **XUserAddAsync** 调用账户选择器

* 对于 ERA 和 UWP，使用 **ShowAccountPickerAsync** 调用账户选择器。

如果用户选择取消登录，游戏必须通知用户：如果继续，其进度将不会被保存。

在选择了用户或从启动中识别出用户后，游戏会在执行任何与个人资料相关的操作之前显示玩家代号。对于游戏如何或在何处显示活动用户，没有任何要求。最佳做法包括在应用的主屏幕或游戏的标题菜单上显示用户的玩家图片和显示名称。

**在初始激活期间建立控制器**

当游戏在已有用户登录的情况下启动时，游戏需要遵循由账户选择器或平台设置的控制器与用户绑定。无论是在游戏过程中还是在游戏过程之外，只要在账户选择器中选择了玩家，XBOX 平台就会将控制器绑定到该玩家。

如果游戏使用启动游戏的用户，则游戏应使用分配给该用户的关联游戏板来驱动游戏过程和交互。

**从挂起或受限模式恢复**

*GDK 简化用户模型*

XBOX 平台将确保最初启动游戏的用户仍处于活动登录状态。游戏可以通过 UDA 注册更改通知；如果发生更改，则使用新绑定的控制器来驱动游戏过程。

从挂起或受限状态恢复时，游戏过程中的任何其他用户都需要按照以下高级用户模型中的指南进行相应处理。

*GDK 高级用户模型、ERA 和 UWP 多用户应用程序*

当游戏从挂起状态恢复或退出受限模式时，游戏必须验证用户/控制器配对，并做出相应反应：

* 如果用户/控制器配对没有变化，则游戏必须继续运行。
* 在 ERA 或 UWP 中，如果游戏先前的活动用户仍处于登录状态，但使用的是新的 User 对象（通常是由于用户在游戏挂起期间注销后又重新登录所致），则游戏必须使用新的已登录 User 对象替换已注销的 User 对象。使用方式必须如同用户从未注销过一样。
* 如果所有预期用户都与有效但不同的控制器配对，则游戏必须更新并使用新的系统控制器配对。
* 如果预期用户没有任何有效的控制器，则游戏必须使用账户选择器为该用户建立活动控制器。
* 如果预期玩家未登录，游戏必须从游戏中移除该玩家，或者重新建立用户和活动控制器。游戏通常通过显示账户选择器来实现这一点。如果在重新建立用户的过程中选择了新用户，并且游戏状态是按用户保存的，则游戏必须使用该新用户的状态进行游戏。

## 其他资源

有关使用 GDK 实现玩家标识的信息，请阅读[用户部分](https://docs.xbox.com/zh-CN/build/core-features/common/user/user-toc.md)

## 认证测试用例

下表显示了在使用 GDK 简化用户模型，或者使用 GDK 高级用户模型、ERA 和 UWP 多用户应用程序时，XR-112 的哪些测试用例适用于你的游戏。

| 测试用例 | 适用于 GDK 简化用户模型 | 适用于 GDK 高级用户模型、ERA 和 UWP MUA |
| - | - | - |
| 112-02 初始用户和控制器 | 否 | 是 |
| 112-03 无已登录用户 | 否 | 是 |
| 112-04 活动用户指示 | 是 | 是 |
| 112-05 访问账户选择器 | 否 | 是 |
| 112-06 处理个人资料更改 | 否 | 是 |
| 112-07 受限模式期间的用户更改 | 否 | 是 |
| 112-08 挂起期间的用户更改 | 否 | 是 |

### 112-02 初始用户和控制器

**测试步骤**

1. 登录个人资料 A 并启动游戏。
2. 验证活动用户可以控制游戏。
3. 在没有已登录个人资料的情况下重复步骤 \[1]，并验证游戏提示建立活动用户。
4. 建立活动用户，并验证该用户可以控制游戏。

**预期结果**\
游戏必须将活动用户设置为启动游戏的控制器/用户配对，或者显示参与提示以识别控制器和用户，或者显示账户选择器以进行登录。

**通过示例**

1. 游戏将活动用户设置为启动游戏的控制器/用户配对。
2. 游戏显示参与提示以识别控制器和用户。
3. 游戏显示账户选择器以进行登录。

**失败示例**

1. 游戏不允许用户使用最先使用的控制器控制游戏。
2. 在没有用户登录的情况下启动游戏时，游戏不提示用户建立活动用户。

### 112-03 无已登录用户

**测试步骤**

1. 验证没有用户登录。
2. 启动游戏，并进入每个支持保存用户数据的模式。
3. 验证每个模式都在发生任何数据丢失之前为用户提供登录机会。
4. 取消登录机会，并验证游戏显示警告，指示进度将不会被保存。

**预期结果**\
如果游戏处于通常会保存用户数据或游戏状态的模式，则游戏必须为用户提供登录机会。如果用户在未登录的情况下继续游戏，游戏必须通知用户其进度将不会被保存

**通过示例**

1. 未登录的用户在访问通常会保存用户数据或游戏状态的游戏模式时，会收到登录提示。
2. 系统通知用户：如果在未登录的情况下继续该模式，进度将不会被保存。

**失败示例**

1. 在通常会保存用户数据或游戏状态的模式下，未通知用户：如果在未登录的情况下继续该模式，进度将不会被保存。
2. 在已经发生数据丢失之后，才通知用户将无法保存其进度。

### 112-04 活动用户指示

**测试步骤**

1. 登录一个以前从未见过该游戏且没有关联保存数据的个人资料。
2. 启动游戏。
3. 验证游戏在执行任何与个人资料相关的操作之前，在 UI 中标识活动用户。“与个人资料相关的操作”的示例包括更改用户的已保存的游戏或首选项、将数据保存到用户的个人资料、授予成就、为用户写入统计信息，或者以任何其他方式在本地或云中使用或操作用户数据或状态。
4. 创建存档。
5. 重新启动游戏，并验证游戏在执行任何与个人资料相关的操作之前，在 UI 中标识活动用户。
6. 断开与 XBOX Live 的连接。
7. 重新启动游戏，并验证游戏在执行任何与个人资料相关的操作之前，在 UI 中标识活动用户。

**预期结果**\
游戏必须在执行第一个与个人资料相关的操作之前指明当前用户上下文。

**通过示例**

1. 游戏在执行任何与个人资料相关的操作之前，在游戏中显示用户的玩家代号和/或玩家图片。
2. 不使用用户个人资料的游戏不指示活动用户。
3. 对于支持多个用户的游戏模式，游戏显示多个活动用户。

**失败示例**

1. 游戏在执行与个人资料相关的操作之前，未指示游戏的活动用户。

### 112-05 访问账户选择器

**测试步骤**

1. 登录一个个人资料并启动游戏。
2. 确认游戏允许活动用户在游戏中访问账户选择器并选择其他个人资料。

**预期结果**\
游戏必须允许用户在游戏中访问账户选择器以更改活动用户。

**通过示例**

1. 游戏允许用户在游戏中访问账户选择器。

**失败示例**

1. 游戏不允许用户在游戏中访问账户选择器。

### 112-06 处理个人资料更改

**测试步骤**

1. 登录一个个人资料并启动游戏。
2. 访问账户选择器并选择其他个人资料。
3. 验证游戏做出适当反应，并将活动用户的上下文切换到新的个人资料。
4. 对游戏中每个可以访问账户选择器的位置重复步骤 1-4。

**预期结果**\
游戏必须允许用户无缝切换到其他用户的上下文。

**通过示例**

1. 游戏通知用户更改活动用户可能会导致数据丢失，并在进入账户选择器之前提示用户确认。
2. 游戏相应地更新为新活动用户的上下文。

**失败示例**

1. 游戏未相应地更新为新活动用户的上下文。

### 112-07 受限模式期间的用户更改

**测试步骤**

1. 登录个人资料 A 并启动游戏。
2. 在游戏中的各个位置，按 XBOX button 使游戏进入受限状态。
3. 在游戏处于受限状态时，注销个人资料 A 并登录个人资料 B。
4. 恢复游戏。
5. 验证游戏针对新的活动用户做出相应反应。

**预期结果**
当游戏从受限模式恢复时，游戏必须验证之前参与的所有用户是否仍登录到主机

**通过示例**

1. 应用程序在恢复时自动将活动用户上下文切换到个人资料 B。
2. 游戏自动从游戏中移除个人资料 A，或者重新建立新用户并使用该新用户的状态进行游戏。

**失败示例**

1. 游戏未进行更新，未将个人资料 A 作为活动用户从上下文中移除。
2. 选择新的个人资料后，游戏继续使用个人资料 A 的状态进行游戏。

### 112-08 挂起期间的用户更改

在零售版主机上，游戏会在以下情况下被挂起：

* 在电源模式设置为“即时启动”时关闭主机，使主机进入联网待机状态。
* 游戏保持非焦点状态十分钟。例如，启动“设置”等应用程序并使其保持焦点状态十分钟。

在本测试用例中，应在步骤 2 中验证这两种方法。

**测试步骤**

1. 登录 XBOX 个人资料并启动游戏。
2. 在游戏中的各个位置挂起游戏。
3. 在游戏挂起期间，注销个人资料 A 并登录个人资料 B。
4. 恢复游戏，并验证游戏针对新的活动用户做出相应反应。
5. 使用新的活动用户进入游戏过程，并验证该用户能够取得进展。

**预期结果**

1. 当游戏从挂起状态恢复时，游戏必须验证之前参与的所有用户是否仍登录到主机。

**通过示例**

1. 游戏在恢复时自动将活动用户上下文切换到个人资料 B。
2. 游戏自动从游戏中移除个人资料 A，或者重新建立新用户并使用该新用户的状态进行游戏。

**失败示例**

1. 游戏未进行更新，未将个人资料 A 作为活动用户从上下文中移除。
2. 选择新的个人资料后，游戏继续使用个人资料 A 的状态进行游戏。


## Related topics

- [XR112 初始激活和恢复时的用户和控制器](https://docs.xbox.com/zh-CN/publishing/certification/fma/xr-112.md)
- [经测试的 XBOX 要求](https://docs.xbox.com/zh-CN/publishing/certification/console-cert-tested-requirements.md)
- [XBOX 游戏的 XBOX 要求](https://docs.xbox.com/zh-CN/publishing/certification/xbox-requirements.md)
- [XBOX 要求和政策支持内容](https://docs.xbox.com/zh-CN/publishing/certification/xr/overview.md)
- [GDK 中的用户身份与 XUser API](https://docs.xbox.com/zh-CN/build/core-features/common/user/index.md)