> ## 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 多人游戏会话中定义玩家角色并保留位置，以便服务跟踪角色分配并强制执行每个游戏角色的最大数量。

本主题描述如何在 XBOX 服务多人游戏中定义玩家角色。对于某些游戏会话，你可能希望将游戏角色（例如支援、医疗或突击）分配给特定的玩家。你还可能希望为可以填补特定游戏角色的玩家保留游戏位置。

通过使用 XBOX 服务角色功能，该服务可以跟踪为每个游戏角色分配了哪些玩家，并强制执行可以选择特定游戏角色的最大玩家数量。

角色最常见的用法是为游戏会话确定特定于游戏的角色。例如，你可以有一个需要一个或两个支援职业、至少一个坦克/重型职业和不超过五个突击职业的游戏模式。

在另一种可能的情况下，你可能希望指定游戏会话可以正好有四名游戏玩家、最多八名观众和恰好一名解说员。

你还可以使用角色为朋友保留位置，同时通过其他方式（例如会话浏览）填补剩余位置。

## 角色类型

*角色类型*表示一组角色定义。每个角色必须定义为角色类型的一部分。角色类型在多人游戏会话文档中定义。

一个玩家只能被分配同一角色类型中的一个角色。例如，如果"class"角色类型包括治疗、坦克和输出，则玩家只能被分配到其中一个角色。

你可以定义多个角色类型，并且玩家可以从每个角色类型中分配一个角色。在前面的场景中，选择治疗角色的玩家如果在单独的角色类型中定义了小队长角色，则也可以分配小队长角色。

## 角色类型属性

定义角色类型时，必须指定以下信息。

* 角色类型的名称。名称必须为小写字母数字，且不超过 100 个字符。
* 角色的定义。
* 角色是否由所有者管理。
* 角色的属性是否可以在会话生命周期内更改。

如果角色类型由所有者管理，则只有会话的所有者玩家才能分配该类型的角色。如果角色类型不由所有者管理，则玩家可以为自己分配角色。

只有为设置了 `hasOwners` 功能的会话，才能指定角色类型由所有者管理。

<Note>XBOX 服务 API (XSAPI) 目前不支持所有者为其他玩家分配角色。</Note>

## 角色属性

定义角色时，必须指定以下信息。

* 角色的名称。名称必须为小写字母数字，且不超过 100 个字符。
* 可以填补该角色的最大玩家数量。该值必须大于零。
* 应填补该角色的目标玩家数量。该值必须大于零，且小于或等于可以填补该角色的最大玩家数量。

当玩家在会话中被分配角色时，前面的信息将记录在多人游戏会话文档中。

服务强制执行可以分配给角色的最大玩家数量，但不强制执行目标数量。

## 创建角色

角色和角色类型通常在会话模板中定义；有关详细信息，请参阅[多人游戏会话模板](/services/xbox-services/multiplayer/mpsd/concepts/live-session-templates)。该服务支持在创建会话期间定义角色类型和角色，但 XSAPI 不支持。

### 在会话模板中定义角色类型和角色

你可以在 XBOX 服务配置期间创建会话模板时定义角色类型和角色。

有关角色类型和角色的信息使用以下格式在会话模板中指定为基级 `roleTypes` 元素。

```json theme={null}
"roleTypes": {
  "myroletype1": { // Must be lowercase alphanumeric.
    "ownerManaged": true, // Can be true only on sessions that have the "hasOwners" capability set.
                          // If true, only the owner of the session can assign this role to players.
    "mutableRoleSettings": ["max", "target"], // Only these role settings can be modified during the
                                              // session. Exclude role settings to lock them.
    "roles": {
      "role1": { // Must be lowercase alphanumeric.
        "max": 3, // Maximum number of players assigned to this role. Enforced by MPSD.
        "target": 2 // Target number of players to assign this role to. Not enforced by MPSD.
      },
      "role2": {
        ...
      }
  },
  "myroletype2": {
    ...
  }
},
```

## 检索多人游戏会话的角色信息

你可以从多人游戏会话或多人游戏搜索句柄中获取有关角色类型、角色以及分配给每个角色的玩家数量的信息。

在 XSAPI 中，有关角色类型和角色的信息存储在数组结构中。

在搜索请求返回的 `XblMultiplayerSearchHandle` 对象中，你可以通过使用角色类型的名称对 [XblMultiplayerSessionRoleTypes](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionroletypes) 数据建立索引来获取有关角色类型的信息。

该调用返回 [XblMultiplayerRoleType](/reference/live/xsapi-c/multiplayer_c/structs/xblmultiplayerroletype) 对象。要获取有关角色的信息，请索引 `Roles` 数组。

[XblMultiplayerRole](/reference/live/xsapi-c/multiplayer_c/structs/xblmultiplayerrole) 对象包含有关角色的信息，包括 `MaxMemberCount`、`MemberXuids`、`MemberCount` 和 `TargetCount`。

## 为玩家分配角色

目前，玩家只能在 XSAPI 中分配自己的角色。要为当前玩家指定角色类型和角色，请将 `XblMultiplayerSessionHandle` 对象传递给 [XblMultiplayerSessionCurrentUserSetRoles](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessioncurrentusersetroles) 方法。

如果尝试将会话写入服务时该角色已满，则 MPSD 会拒绝写入。


## Related topics

- [多人游戏概念](/zh-CN/services/xbox-services/multiplayer/concepts/live-multiplayer-concepts-nav.md)
- [XblMultiplayerRole](/zh-CN/reference/live/xsapi-c/multiplayer_c/structs/xblmultiplayerrole.md)
- [XblMultiplayerRoleType](/zh-CN/reference/live/xsapi-c/multiplayer_c/structs/xblmultiplayerroletype.md)
- [XblMutableRoleSettings](/zh-CN/reference/live/xsapi-c/multiplayer_c/enums/xblmutablerolesettings.md)
- [概念](/zh-CN/services/xbox-services/multiplayer/concepts/index.md)