> ## 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 services 멀티플레이어에서 플레이어 역할을 정의하는 방법을 설명합니다. 일부 게임 세션에서는 지원, 의무, 공격과 같은 게임플레이 역할을 특정 플레이어에게 할당하고 싶을 수 있습니다. 특정 게임플레이 역할을 수행할 수 있는 플레이어에 대한 게임 슬롯을 예약하고 싶을 수도 있습니다.

XBOX services 역할 기능을 사용하면 서비스가 각 게임플레이 역할에 할당된 플레이어를 추적하고 특정 게임플레이 역할을 선택할 수 있는 최대 플레이어 수를 강제할 수 있습니다.

역할의 가장 일반적인 사용은 게임 세션에 대한 게임별 역할을 결정하는 것입니다. 예를 들어, 하나 또는 두 개의 지원 클래스, 최소 한 개의 탱크/헤비 클래스, 그리고 다섯 개 이하의 공격 클래스가 필요한 게임 모드를 가질 수 있습니다.

또 다른 가능한 시나리오에서는 정확히 네 명의 게임 플레이어, 최대 여덟 명의 관전자, 그리고 정확히 한 명의 진행자가 있는 게임 세션을 지정하고 싶을 수 있습니다.

또한 세션 브라우저와 같은 다른 방법을 통해 나머지 슬롯을 채우면서 친구를 위해 슬롯을 예약하는 데 역할을 사용할 수도 있습니다.

## 역할 유형(Role types)

*역할 유형*은 역할 정의 그룹을 나타냅니다. 각 역할은 역할 유형의 일부로 정의되어야 합니다. 역할 유형은 멀티플레이어 세션 문서에서 정의됩니다.

플레이어는 하나의 역할 유형에서 하나의 역할만 할당받을 수 있습니다. 예를 들어 "class" 역할 유형에 힐러, 탱커, 딜러가 포함되어 있다면 플레이어는 그중 하나의 역할만 할당받을 수 있습니다.

여러 역할 유형을 정의할 수 있으며, 플레이어는 각 역할 유형에서 하나의 역할을 할당받을 수 있습니다. 이전 시나리오에서, 힐러 역할을 선택한 플레이어는 분대장 역할이 별도의 역할 유형에 정의되어 있다면 분대장 역할도 할당받을 수 있습니다.

## 역할 유형 속성

역할 유형을 정의할 때 다음 정보를 지정해야 합니다.

* 역할 유형의 이름. 이름은 소문자 영숫자여야 하며 100자를 초과할 수 없습니다.
* 역할의 정의.
* 역할이 소유자 관리인지 여부.
* 세션 수명 동안 역할의 속성을 변경할 수 있는지 여부.

역할 유형이 소유자 관리인 경우 세션의 소유자인 플레이어만 해당 유형의 역할을 할당할 수 있습니다. 역할 유형이 소유자 관리가 아닌 경우 플레이어는 자신에게 역할을 할당할 수 있습니다.

`hasOwners` 기능이 설정된 세션에 대해서만 역할 유형을 소유자 관리로 지정할 수 있습니다.

<Note>XBOX Services API(XSAPI)는 현재 소유자가 다른 플레이어에게 역할을 할당하는 것을 지원하지 않습니다.</Note>

## 역할 속성

역할을 정의할 때 다음 정보를 지정해야 합니다.

* 역할의 이름. 이름은 소문자 영숫자여야 하며 100자를 초과할 수 없습니다.
* 역할을 채울 수 있는 최대 플레이어 수. 값은 0보다 커야 합니다.
* 역할을 채워야 할 목표 플레이어 수. 값은 0보다 크고 역할을 채울 수 있는 최대 플레이어 수보다 작거나 같아야 합니다.

플레이어가 세션에서 역할을 할당받으면 앞의 정보가 멀티플레이어 세션 문서에 기록됩니다.

서비스는 역할에 할당될 수 있는 최대 플레이어 수를 강제하지만, 목표 수는 강제하지 않습니다.

## 역할 만들기

역할 및 역할 유형은 일반적으로 세션 템플릿에 정의됩니다. 자세한 내용은 [멀티플레이어 세션 템플릿](/services/xbox-services/multiplayer/mpsd/concepts/live-session-templates)을 참조하세요. 서비스는 세션 생성 중 역할 유형 및 역할 정의를 지원하지만 XSAPI는 그렇지 않습니다.

### 세션 템플릿에서 역할 유형 및 역할 정의

XBOX services 구성 중에 세션 템플릿을 만들 때 역할 유형 및 역할을 정의할 수 있습니다.

역할 유형 및 역할에 관한 정보는 다음 형식을 사용하여 세션 템플릿에서 기본 수준의 `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

- [멀티플레이어 개념](/ko/services/xbox-services/multiplayer/concepts/live-multiplayer-concepts-nav.md)
- [개념](/ko/services/xbox-services/multiplayer/concepts/index.md)
- [XblMultiplayerRole](/ko/reference/live/xsapi-c/multiplayer_c/structs/xblmultiplayerrole.md)
- [멀티플레이어 세션 템플릿](/ko/services/xbox-services/multiplayer/mpsd/concepts/live-session-templates.md)
- [멀티플레이어 개념 개요](/ko/services/xbox-services/multiplayer/concepts/live-multiplayer-concepts.md)