> ## 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 服務角色功能，服務可以追蹤哪些玩家被指派了每個遊戲角色，並強制執行可以選取特定遊戲角色的玩家數目上限。

角色最常見的用途是為遊戲工作階段決定遊戲特定的角色。例如，您可以有一個需要一或兩個支援職業、至少一個坦克/重裝職業，以及不超過五個突擊職業的遊戲模式。

在另一個可能的案例中，您可能想要指定遊戲工作階段可以有剛好四位遊戲玩家、最多八位觀眾，以及剛好一位播報員。

您也可以使用角色為好友保留位置，同時透過其他方式 (例如工作階段瀏覽) 填滿剩餘的位置。

## 角色類型

*角色類型*代表一組角色定義。每個角色都必須定義為角色類型的一部分。角色類型是在多人遊戲工作階段文件中定義的。

玩家只能從一個角色類型中被指派一個角色。例如，如果「職業」角色類型包括治療者、坦克和輸出，則玩家只能被指派到其中一個角色。

您可以定義多個角色類型，而玩家可以從每個角色類型中被指派一個角色。在上述案例中，如果在個別的角色類型中定義了小隊隊長角色，則選擇治療者角色的玩家也可以被指派小隊隊長角色。

## 角色類型屬性

定義角色類型時，您必須指定下列資訊。

* 角色類型的名稱。名稱必須是小寫英數字元，且不得超過 100 個字元。
* 角色的定義。
* 角色是否由擁有者管理。
* 角色的屬性是否可以在工作階段的存留期間變更。

如果角色類型由擁有者管理，則只有身為工作階段擁有者的玩家才能指派該類型的角色。如果角色類型不是由擁有者管理，玩家可以為自己指派角色。

您只能為已設定 `hasOwners` 功能的工作階段指定角色類型由擁有者管理。

<Note>XBOX 服務 API (XSAPI) 目前不支援擁有者將角色指派給其他玩家。</Note>

## 角色屬性

定義角色時，您必須指定下列資訊。

* 角色的名稱。名稱必須是小寫英數字元，且不得超過 100 個字元。
* 可以擔任該角色的玩家數目上限。值必須大於零。
* 應擔任該角色的目標玩家數目。值必須大於零，且小於或等於可以擔任該角色的玩家數目上限。

當玩家在工作階段中被指派角色時，上述資訊會記錄在多人遊戲工作階段文件中。

服務會強制執行可指派給角色的玩家數目上限，但不會強制執行目標數目。

## 建立角色

角色和角色類型通常是在工作階段範本中定義的；如需詳細資訊，請參閱[多人遊戲工作階段範本](/zh-TW/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](/zh-TW/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionroletypes) 資料建立索引，以取得角色類型的相關資訊。

此呼叫會傳回 [XblMultiplayerRoleType](/zh-TW/reference/live/xsapi-c/multiplayer_c/structs/xblmultiplayerroletype) 物件。若要取得角色的相關資訊，請為 `Roles` 陣列建立索引。

[XblMultiplayerRole](/zh-TW/reference/live/xsapi-c/multiplayer_c/structs/xblmultiplayerrole) 物件包含角色的相關資訊，包括 `MaxMemberCount`、`MemberXuids`、`MemberCount` 和 `TargetCount`。

## 將角色指派給玩家

目前，在 XSAPI 中，玩家只能指派自己的角色。若要為目前玩家指定角色類型和角色，請將 `XblMultiplayerSessionHandle` 物件傳遞至 [XblMultiplayerSessionCurrentUserSetRoles](/zh-TW/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessioncurrentusersetroles) 方法。

如果在您嘗試將工作階段寫入服務時角色已滿，MPSD 會拒絕寫入。


## Related topics

- [多人遊戲概念](/zh-TW/services/xbox-services/multiplayer/concepts/live-multiplayer-concepts-nav.md)
- [多人遊戲工作階段瀏覽](/zh-TW/services/xbox-services/multiplayer/concepts/live-session-browse.md)
- [XblMultiplayerRole](/zh-TW/reference/live/xsapi-c/multiplayer_c/structs/xblmultiplayerrole.md)
- [XblMultiplayerRoleType](/zh-TW/reference/live/xsapi-c/multiplayer_c/structs/xblmultiplayerroletype.md)
- [XblMutableRoleSettings](/zh-TW/reference/live/xsapi-c/multiplayer_c/enums/xblmutablerolesettings.md)