> ## 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.

# Multiplayer Manager 개요

> MPSD 세션 관리, SmartMatch 매치메이킹, 초대, 진행 중 참여를 간소화하는 상위 수준 XBOX Live API인 Multiplayer Manager 개요입니다.

이 항목에서는 세션, 매치메이킹 및 게임 초대를 관리하여 멀티플레이어 기능을 추가하기 위한 상위 수준 API를 설명합니다. API는 상태 기반 및 이벤트 기반 프로그래밍 모델을 제공합니다.

XBOX services는 타이틀에 멀티플레이어 기능을 추가하기 위한 광범위한 지원을 제공하여 게임이 전 세계의 XBOX 멤버들을 연결할 수 있도록 합니다.
여기에는 풍부한 매치메이킹 시나리오, 플레이어가 진행 중인 친구의 게임에 참여할 수 있는 기능 등이 포함됩니다.

멀티플레이어 API를 직접 사용하여 XBOX services 멀티플레이어를 구현하는 것은 복잡한 작업일 수 있습니다. 모범 사례를 준수하고 인증 요구 사항을 충족하는지 확인하기 위한 상당한 정도의 설계 및 테스트가 필요합니다.

Multiplayer Manager는 세션 및 매치메이킹을 관리하고 상태 기반 및 이벤트 기반 프로그래밍 모델을 제공함으로써 게임에 멀티플레이어 기능을 쉽게 추가할 수 있도록 합니다.

Multiplayer Manager는 API 집합입니다. 이는 P2P 호스팅 멀티플레이어 디자인의 XBOX services 게임에 대한 멀티플레이어 시나리오를 쉽게 구현할 수 있도록 설계되었습니다.

Multiplayer Manager는 친구와의 멀티플레이어 게임 플레이, 게임 초대 처리, 진행 중 참여 처리, 매치메이킹 등 일반적인 멀티플레이어 시나리오에 중점을 둔 API를 제공합니다.

Multiplayer Manager는 여러 로컬 사용자를 지원합니다. 또한 타사 매치메이킹 서비스를 사용하는 경우 타이틀이 MPSD(Multiplayer Session Directory)와 더 쉽게 통합할 수 있게 해줍니다. 이러한 많은 시나리오는 몇 번의 API 호출만으로 수행할 수 있습니다.

## 주요 기능

Multiplayer Manager API의 주요 기능은 다음과 같습니다.

* 간편한 세션 관리 및 XBOX services 매치메이킹
* 상태 기반 및 이벤트 기반 프로그래밍 모델
* XBOX services 모범 사례 준수 및 Multiplayer XR 규정 준수
* 2015 멀티플레이어 흐름도 구현

Multiplayer Manager API 디자인에 대한 중요한 정보는 다음과 같습니다.

* 대규모 MPSD 세션(100명 이상의 멤버)은 지원되지 않습니다.
* P2P 호스팅 멀티플레이어 디자인만 대상으로 합니다. 전용 서버가 있는 타이틀은 대신 [Multiplayer Activity Service](/services/xbox-services/multiplayer/mpa/live-mpa-overview) 또는 [Multiplayer Service API](/services/xbox-services/multiplayer/mpsd/live-mpsd-overview) 및 [서비스 간 호출(NDA 항목)](/services/xbox-services/fundamentals/s2s-auth-calls/s2s-calls/live-title-service-calls-xbox-live)을 사용해야 합니다.

<Info>인증을 통과하려면 게임에서 여전히 온라인 멀티플레이어에 대한 필수 이벤트를 구현해야 합니다.</Info>

## 개요

Multiplayer Manager는 다음 주요 개념을 중심으로 합니다.

* **로비 세션:** 디바이스에 로컬인 사용자와 함께 플레이하려는 초대된 친구를 관리하는 데 사용되는 영구 세션입니다.

  그룹은 여러 라운드, 맵, 레벨과 같은 게임을 플레이할 수 있습니다. 로비 세션은 이 핵심 친구 그룹(디바이스에 로컬인 플레이어 포함)을 추적합니다.
  일반적으로 이 그룹은 호스트가 메뉴를 탐색하고 그룹 멤버와 채팅하며 어떤 게임 모드를 플레이할지 결정할 때 형성됩니다.

* **게임 세션:** 게임의 특정 인스턴스를 플레이하는 플레이어를 추적합니다.

  예를 들어 레이스, 맵 또는 레벨입니다.
  [XblMultiplayerManagerJoinGameFromLobby](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoingamefromlobby)를 통해 로비 세션의 멤버를 포함하는 새 게임 세션을 만들 수 있습니다.

  멤버가 초대를 수락하면 그들은 로비와 (자리가 있으면) 게임 세션에 추가됩니다.

  매치메이킹이 활성화된 경우 게임 세션에 추가 플레이어를 추가할 수 있지만 이러한 추가 플레이어는 로비 세션에 추가되지 않습니다.
  즉, 게임이 종료되면 로비 세션의 플레이어는 여전히 함께 있지만 매치메이킹에서 온 추가 플레이어는 함께 있지 않습니다.

* [XblMultiplayerManagerMember](/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayermanagermember): 로컬 또는 원격 디바이스에 로그인된 개별 사용자를 나타냅니다.

* [XblMultiplayerManagerDoWork](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork): 타이틀과 XBOX services 멀티플레이어 서비스 간에 적절한 게임 상태 업데이트가 유지되도록 합니다.

  최상의 성능을 보장하려면 [XblMultiplayerManagerDoWork](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork)를 프레임당 한 번씩과 같이 자주 호출해야 합니다.

  [XblMultiplayerManagerDoWork](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork)는 게임이 처리할 [XblMultiplayerEvent](/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayerevent) 콜백 이벤트 배열을 제공합니다.

## 상태 머신

[XblMultiplayerManagerDoWork](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork) 호출은 상태를 최신 상태로 유지하기 위해 필요합니다.
Multiplayer Manager가 작업을 수행하려면 [XblMultiplayerManagerDoWork](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork) 메서드를 정기적으로 호출해야 합니다.
이를 수행하는 가장 안정적인 방법은 프레임당 최소 한 번 호출하는 것입니다.

[XblMultiplayerManagerDoWork](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork)는 수행할 작업이 없을 때 빠르게 반환되므로 너무 자주 호출하는 것에 대해 걱정할 필요가 없습니다.

### 스레딩

Multiplayer Manager API에서 반환된 모든 객체는 스레드 안전으로 간주되어서는 안 됩니다.
그러나 여러 스레드에서 호출하는 경우 스레드 동기화를 수행할 수 있는 제어권을 제공합니다.

라이브러리에는 내부 다중 스레드 보호가 있습니다. 그러나 한 스레드가 특정 값에 액세스해야 하는 경우 여전히 자체 잠금을 구현해야 합니다. 예를 들어 다른 스레드가 [XblMultiplayerManagerDoWork](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork)를 호출하는 동안 멤버 목록을 순회하는 경우 등이 있습니다.

### 상태 기반 모델 업데이트

Multiplayer Manager는 플레이어가 참여, 이탈 또는 세션이 업데이트될 때 백그라운드에서 세션을 업데이트하는 상태 기반 모델을 유지합니다.
UI 스레드와 게임 스레드 간의 스레드 동기화 문제를 피하기 위해 Multiplayer Manager는 [XblMultiplayerManagerDoWork](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork) 메서드를 호출할 때까지 세션의 앱에서 볼 수 있는 상태를 업데이트하지 않습니다.

전통적으로는 백그라운드 스레드에서 세션 변경과 같은 이벤트에 대한 알림을 받은 다음, 이러한 변경 사항을 표시하기 위해 UI 스레드와 동기화해야 합니다.
Multiplayer Manager를 사용하면 이러한 백그라운드 작업이 자동으로 수행됩니다.

원하는 시점에 메인 스레드에서 [XblMultiplayerManagerDoWork](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork)를 호출하여 Multiplayer Manager가 뒤에서 버퍼링하고 있는 상태의 최신 스냅샷을 얻을 수 있습니다.

## 이벤트 및 알림

Multiplayer Manager는 중요한 이벤트 집합([XblMultiplayerEvent](/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayerevent) 참조)을 정의하고 이벤트가 발생하면 [XblMultiplayerManagerDoWork](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork) 메서드를 통해 타이틀에 알립니다.
예를 들어 이벤트에는 원격 플레이어의 참여 또는 이탈, 멤버 속성 변경, 세션 상태 변경 등이 포함됩니다.

모든 Multiplayer Manager API는 비동기적입니다.
[XblMultiplayerManagerDoWork](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork) 메서드는 이러한 비동기 작업이 완료되면 이벤트 목록을 반환합니다.
타이틀은 상황에 맞게 이러한 이벤트를 적절히 처리해야 합니다.
자세한 내용은 [XblMultiplayerEvent](/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayerevent) 클래스 문서를 참조하세요.

반환된 각 [XblMultiplayerEvent](/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayerevent)에는 이벤트 유형에 대한 적절한 `args`를 가져오기 위해 사용해야 하는 `EventArgsHandle`이 포함됩니다.
예를 들어 [XblMultiplayerEventType](/reference/live/xsapi-c/multiplayer_manager_c/enums/xblmultiplayereventtype)이 `MemberJoined`인 경우, [XblMultiplayerEventArgsMembersCount](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayereventargsmemberscount) 및 [XblMultiplayerEventArgsMembers](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayereventargsmembers)를 호출할 수 있습니다.

다음 예제는 이벤트를 처리하기 위해 [XblMultiplayerManagerDoWork](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork)를 사용하는 방법을 보여줍니다.

#### Flat C API

```cpp theme={null}
size_t eventCount{ 0 };
const XblMultiplayerEvent* events{ nullptr };
HRESULT hr = XblMultiplayerManagerDoWork(&events, &eventCount);
if (FAILED(hr))
{
    // Handle failure.
}

for (auto i = 0u; i < eventCount; ++i)
{
    switch (events[i].EventType)
    {
        case XblMultiplayerEventType::MemberJoined:
        {
            // Handle MemberJoined.
            size_t memberCount = 0;
            hr = XblMultiplayerEventArgsMembersCount(events[i].EventArgsHandle, &memberCount);
            assert(SUCCEEDED(hr));

            std::vector<XblMultiplayerManagerMember> members(memberCount);
            hr = XblMultiplayerEventArgsMembers(events[i].EventArgsHandle, memberCount, members.data());
            assert(SUCCEEDED(hr));
            ...

            break;
        }

        case XblMultiplayerEventType::SessionPropertyChanged:
        {
            // Handle SessionPropertyChanged.
            const char* changedProperty{ nullptr };
            hr = XblMultiplayerEventArgsPropertiesJson(events[i].EventArgsHandle, &changedProperty);
            assert(SUCCEEDED(hr));
            ...

            break;
        }
        ...
    }
}
```

자세한 내용은 다음을 참조하세요.

* [XblMultiplayerEvent](/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayerevent)
* [XblMultiplayerEventArgsMembers](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayereventargsmembers)
* [XblMultiplayerEventArgsMembersCount](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayereventargsmemberscount)
* [XblMultiplayerEventArgsPropertiesJson](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayereventargspropertiesjson)
* [XblMultiplayerEventType](/reference/live/xsapi-c/multiplayer_manager_c/enums/xblmultiplayereventtype)
* [XblMultiplayerManagerDoWork](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork)
* [XblMultiplayerManagerMember](/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayermanagermember)

## 시나리오

이 섹션에서는 일반적인 시나리오와 각 시나리오에서 호출할 API를 다룹니다.
Multiplayer Manager가 뒤에서 수행하는 작업에 대한 일부 정보도 제공됩니다.

* [Multiplayer Manager를 사용하여 친구와 멀티플레이어 게임 플레이 활성화](/services/xbox-services/multiplayer/mpm/how-to/live-play-multiplayer-with-friends)
* [Multiplayer Manager를 사용한 SmartMatch로 멀티플레이어 게임 찾기](/services/xbox-services/multiplayer/mpm/how-to/live-play-multiplayer-with-matchmaking)
* [Multiplayer Manager를 사용하여 게임 초대 보내기](/services/xbox-services/multiplayer/mpm/how-to/live-send-game-invites)
* [Multiplayer Manager를 사용하여 게임을 시작하기 위한 프로토콜 활성화 처리](/services/xbox-services/multiplayer/mpm/how-to/live-handle-protocol-activation)

API에 대한 상위 수준 개요는 [Multiplayer Manager API 개요](/services/xbox-services/multiplayer/mpm/concepts/live-multiplayer-manager-api-overview)를 참조하세요.

## Multiplayer Manager가 수행하지 않는 작업

Multiplayer Manager는 멀티플레이어 시나리오를 훨씬 쉽게 구현할 수 있게 해주고 일부 데이터를 추상화합니다. 그러나 Multiplayer Manager는 다음을 처리하지 않습니다.

* MMO(대규모 다중 사용자 온라인) 게임 또는 대규모 세션(세션당 100명 이상의 플레이어)이 필요한 기타 게임 유형과 같은 지속적인 온라인 서버 게임
* 서버 대 서버 세션 관리
* [세분화된 속도 제한](/services/xbox-services/develop/best-practices/live-fine-grained-rate-limiting)을 준수하기 위한 MPSD 호출 조절
* Multiplayer 서비스 API와 Multiplayer Manager API 혼합

<Note>Multiplayer Manager는 특정 네트워크 기술에 제한되지 않으며 모든 네트워크 통신 계층과 함께 작동해야 합니다.</Note>

## 리소스

API 작동 예제는 [NetRumble 샘플](https://aka.ms/gdkdl)을 참조하세요.

API 문서는 [multiplayer\_manager\_c](/reference/live/xsapi-c/multiplayer_manager_c/multiplayer_manager_c_members)를 참조하세요.
`multiplayer_manager_c.h` 헤더 파일도 볼 수 있습니다.

질문, 피드백이 있거나 Multiplayer Manager 사용에 문제가 있는 경우, 개발자 계정 관리자(DAM)에게 문의하거나 [https://forums.xboxlive.com](https://forums.xboxlive.com) 포럼에 지원 스레드를 게시하세요.


## Related topics

- [Multiplayer Manager(MPM)](/ko/services/xbox-services/multiplayer/mpm/live-multiplayer-manager-nav.md)
- [XBOX services 멀티플레이어 개요](/ko/services/xbox-services/multiplayer/overviews/live-multiplayer-intro.md)
- [Multiplayer Manager API 개요](/ko/services/xbox-services/multiplayer/mpm/concepts/live-multiplayer-manager-api-overview.md)
- [Social Manager 개요](/ko/services/xbox-services/community/social-manager/live-social-manager-overview.md)
- [Multiplayer Manager 개념](/ko/services/xbox-services/multiplayer/mpm/concepts/live-mm-concepts-nav.md)