멀티플레이어 작업

• Multiplayer Session Directory(MPSD) 세션 변경 알림 구독
• MPSD 세션 생성
• MPSD 세션의 중재자 설정
• 타이틀 활성화 관리
• 사용자를 참가 가능하게 만들기
• 게임 초대 전송
• 로비 세션에서 게임 세션에 참가
• 타이틀 활성화에서 MPSD 세션에 참가
• 사용자의 현재 액티비티 설정
• MPSD 세션 업데이트
• MPSD 세션 나가기
• 매치메이킹 중 열려 있는 세션 슬롯 채우기
• 매치 티켓 생성
• 매치 티켓 상태 가져오기

​

Multiplayer Session Directory(MPSD) 세션 변경 알림 구독

1. 동일한 사용자의 모든 호출에 동일한 XblContextHandle 객체를 사용합니다. 구독은 이 객체의 수명과 연결되어 있습니다. 여러 로컬 사용자가 있는 경우 각 사용자마다 별도의 XblContextHandle 객체를 사용합니다.
2. XblMultiplayerAddSessionChangedHandler 및 XblMultiplayerSessionSubscriptionLostHandler에 대한 이벤트 처리기를 구현합니다.
3. 둘 이상의 사용자에 대해 변경 사항을 구독하는 경우 불필요한 작업을 피하기 위해 XblMultiplayerAddSessionChangedHandler 이벤트 처리기에 코드를 추가합니다. XblMultiplayerSessionChangeEventArgs::Branch 속성과 XblMultiplayerSessionChangeEventArgs::ChangeNumber 속성을 사용합니다. 이러한 속성을 사용하면 마지막으로 확인한 변경 사항을 추적하고 이전 변경 사항을 무시할 수 있습니다.
4. 구독을 허용하려면 XblMultiplayerSetSubscriptionsEnabled를 호출합니다.
5. 로컬 세션 객체를 만든 다음, 해당 세션에 활성 상태로 참가합니다.
6. 각 사용자에 대해 XblMultiplayerAddSessionChangedHandler를 호출하여 알림을 받을 세션 변경 유형을 전달합니다.
7. 이 항목의 MPSD 세션 업데이트 섹션에 설명된 대로 세션을 MPSD에 씁니다.

​

중복 세션 변경 알림 구문 분석

• 평가된 각 Branch 속성 값에 대해 가장 최근의 ChangeNumber 속성 값을 저장합니다.
• 숄더 탭의 ChangeNumber 속성 값이 해당 Branch 속성 값에 대해 저장된 최신 값보다 높으면 숄더 탭을 처리한 다음 가장 최근의 ChangeNumber 속성 값을 업데이트합니다.
• 숄더 탭에 해당 Branch 속성 값에 대해 더 높은 ChangeNumber 속성 값이 없으면 숄더 탭 처리를 건너뜁니다. 해당 세션 변경 사항은 이미 처리되었습니다.

​

MPSD 세션 생성

1. 새 XblContextHandle 객체를 만듭니다. 타이틀은 이 객체를 한 번 만들어 저장한 후 소스 코드 전체에서 필요에 따라 재사용합니다. 특히 세션 구독 작업 시 정확히 동일한 컨텍스트를 사용하는 것이 필수입니다.
2. XblMultiplayerSessionCreateHandle을 사용하여 새 XblMultiplayerSessionHandle을 만들어 MPSD가 새 세션을 만드는 데 필요한 모든 세션 데이터를 준비합니다.
3. 세션을 MPSD에 쓰기 전에 필요한 변경 사항을 수행합니다. 예를 들어 XblMultiplayerSessionJoin 호출로 구성원을 세션에 참가시킬 때, 클라이언트는 세션 업데이트 호출 시 참가하도록 MPSD에 지시하는 숨겨진 로컬 요청 데이터를 추가합니다.
4. 로컬 변경이 완료되면 이 항목의 MPSD 세션 업데이트 섹션에 설명된 대로 MPSD에 씁니다.
5. 많은 필드가 채워진 새 XblMultiplayerSessionHandle 객체를 MPSD로부터 받습니다.
6. 이후에는 새 세션 객체를 사용합니다. 새 세션을 만들라는 숨겨진 요청이 포함된 이전 사본은 폐기합니다.

​

예제

auto asyncBlock = std::make_unique<XAsyncBlock>();
asyncBlock->queue = queue;
asyncBlock->context = nullptr;
asyncBlock->callback = [](XAsyncBlock* asyncBlock)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock }; // Take over ownership of the XAsyncBlock*.

    XblMultiplayerSessionHandle sessionHandle;
    HRESULT hr = XblMultiplayerWriteSessionResult(asyncBlock, &sessionHandle);
    if (SUCCEEDED(hr))
    {
        // Process multiplayer session handle.
    }
    else
    {
        // Handle failure.
    }
};

XblMultiplayerSessionReference ref;
pal::strcpy(ref.Scid, sizeof(ref.Scid), SCID);
pal::strcpy(ref.SessionTemplateName, sizeof(ref.SessionTemplateName), SESSION_TEMPLATE_NAME);
pal::strcpy(ref.SessionName, sizeof(ref.SessionName), SESSION_NAME);

XblMultiplayerSessionInitArgs args = {};

XblMultiplayerSessionHandle sessionHandle = XblMultiplayerSessionCreateHandle(XUID, &ref, &args);

auto hr = XblMultiplayerSessionJoin(
    sessionHandle,
    memberCustomConstantsJson.c_str(),
    initializeRequested,
    joinWithActiveStatus);
    
 hr = XblMultiplayerWriteSessionAsync(xblContextHandle, sessionHandle, XblMultiplayerSessionWriteMode::CreateNew, asyncBlock.get());
if (SUCCEEDED(hr))
{
    // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* because the callback will take over ownership.
    // If the call fails, std::unique_ptr will keep ownership and delete XAsyncBlock*.
    asyncBlock.release();
}

• XAsyncBlock
• XblMultiplayerSessionCreateHandle
• XblMultiplayerSessionInitArgs
• XblMultiplayerSessionReference
• XblMultiplayerSessionWriteMode
• XblMultiplayerWriteSessionAsync
• XblMultiplayerWriteSessionResult

​

MPSD 세션의 중재자 설정

1. XblMultiplayerSessionMembers를 호출하여 MPSD에서 호스트 후보의 디바이스 토큰을 검색합니다.

   [!NOTE] 세션이 SmartMatch 매치메이킹으로 생성된 경우, 클라이언트는 XblMultiplayerSessionHostCandidates를 호출하여 MPSD에서 사용할 수 있는 호스트 후보를 사용할 수 있습니다.

2. 호스트 후보 목록에서 필요한 호스트를 선택합니다.
3. XblMultiplayerSessionSetHostDeviceToken을 호출하여 MPSD의 로컬 캐시에 디바이스 토큰을 설정합니다. 호스트 디바이스 토큰 설정 호출이 성공하면 로컬 디바이스 토큰이 호스트의 토큰을 대체합니다.
4. 호스트 디바이스 토큰을 설정하려고 할 때 HTTP/412 상태 코드가 수신되면 세션 데이터를 쿼리합니다. 호스트 디바이스 토큰이 로컬 콘솔의 것인지 확인합니다. 로컬 콘솔의 것이 아니라면 다른 콘솔이 중재자로 지정된 것입니다.

   [!NOTE] HTTP/412는 표준 실패를 나타내지 않으므로 클라이언트는 HTTP/412 상태 코드를 다른 HTTP 코드와 별도로 처리해야 합니다. 이 상태 코드에 대한 자세한 내용은 멀티플레이어 세션 상태 코드를 참조하세요.

5. 이 항목의 MPSD 세션 업데이트 섹션에 설명된 대로 MPSD의 세션을 업데이트합니다.

   [!NOTE] 더 나은 알고리즘이 없다면, 각 호스트 후보가 아직 아무도 그렇게 하지 않았을 때 스스로 호스트로 설정하려고 하는 그리디 알고리즘을 클라이언트에서 구현할 수 있습니다. 자세한 내용은 Multiplayer Session 고급 항목의 세션 중재자 섹션을 참조하세요.

​

타이틀 활성화 관리

1. CoreApplicationView.Activated 이벤트에 대한 이벤트 처리기를 설정합니다. 이 처리기는 타이틀이 이미 실행 중이더라도 프로토콜 활성화가 발생할 때마다 트리거됩니다.
2. 타이틀 활성화 시 세션을 시작하고 세션 변경 알림을 구독합니다. 자세한 내용은 이 항목의 MPSD 세션 변경 알림 구독을 참조하세요.
3. 사용자를 세션에 활성 상태로 참가시킵니다. 자세한 내용은 이 항목의 타이틀 활성화에서 MPSD 세션에 참가를 참조하세요.
4. 프로필 UI를 통해 노출되는 액티비티 세션으로 로비 세션을 설정합니다. 자세한 내용은 이 항목의 사용자의 현재 액티비티 설정을 참조하세요.
5. 사용자를 게임 세션에 활성 상태로 참가시킵니다. 이제 사용자는 피어에 연결하여 게임 플레이 또는 로비에 진입할 수 있습니다.

​

사용자를 참가 가능하게 만들기

1. 세션 객체를 만든 다음 필요에 따라 속성을 수정합니다.
2. 사용자를 세션에 활성 상태로 참가시킵니다. 자세한 내용은 이 항목의 타이틀 활성화에서 MPSD 세션에 참가를 참조하세요.
3. 사용자가 세션 중재자로 지정되었는지 확인합니다.
4. 사용자가 중재자가 아닌 경우 7단계로 이동합니다.
5. 사용자가 중재자이면 XblMultiplayerSessionSetHostDeviceToken을 호출합니다.
6. XblMultiplayerWriteSessionAsync 호출을 사용하여 세션을 쓰려고 시도합니다.
7. 세션을 활성 세션으로 설정합니다. 자세한 내용은 이 항목의 사용자의 현재 액티비티 설정을 참조하세요.

​

게임 초대 전송

• 로비 세션에 대한 초대를 보냅니다.
• 게임 세션 참조를 사용하여 일반 XBOX 플랫폼 초대 UI를 통해 초대를 보냅니다.

1. 초대하는 게임 플레이어를 참가 가능하게 만듭니다. 자세한 내용은 이 항목의 사용자를 참가 가능하게 만들기를 참조하세요.
2. 초대를 로비 세션을 통해 보낼지 아니면 초대 UI를 사용하여 보낼지 결정합니다.
3. 로비 세션이 사용되는 경우, XblMultiplayerSendInvitesAsync 호출을 사용하여 초대를 보냅니다. 이 메서드는 XGameUiShowPlayerPickerAsync를 호출하여 게임 내 UI 명단을 만들어야 할 수도 있습니다.
4. 초대 UI가 사용되는 경우 XGameUiShowSendGameInviteAsync를 호출하여 초대 UI를 표시합니다.
5. 원격 플레이어가 참가한 후 로컬 플레이어에 대한 XblMultiplayerAddSessionChangedHandler를 처리합니다.
6. 원격 플레이어의 경우 타이틀 활성화 코드를 구현합니다. 자세한 내용은 이 항목의 타이틀 활성화 관리를 참조하세요.

​

로비 세션에서 게임 세션에 참가

1. 게임 세션을 만들 때 XblMultiplayerSetTransferHandleAsync API를 사용하여 로비 세션과 게임 세션을 연결하는 전송 핸들을 만듭니다.
2. 게임 세션의 세션 참조 대신 로비 세션에 전송 핸들 GUID를 저장합니다.
3. 타이틀이 구성원을 로비 세션에서 게임 세션으로 이동시키려는 경우, 각 클라이언트는 로비 세션의 전송 핸들을 사용하여 XblMultiplayerWriteSessionByHandleAsync API를 통해 게임 세션에 참가합니다.
4. MPSD는 로비 세션을 조회하여 전송 핸들을 사용하여 게임 세션에 참가하려는 구성원이 로비 세션에도 있는지 확인합니다.
5. 구성원이 로비 세션에 있으면 게임 세션에 액세스할 수 있습니다.

​

타이틀 활성화에서 MPSD 세션에 참가

1. CoreApplicationView.Activated 이벤트에 대한 이벤트 처리기를 구현합니다. 이는 타이틀에 대한 활성화를 알립니다.
2. 처리기가 실행되면 IActivatedEventArgs.Kind 속성을 검사합니다. Protocol로 설정되어 있으면 이벤트 인수를 ProtocolActivatedEventArgs 클래스로 캐스팅합니다.
3. ProtocolActivatedEventArgs 객체를 검사합니다. ProtocolActivatedEventArgs.Uri 속성에 지정된 URI가 inviteHandleAccept(수락된 초대에 해당) 또는 activityHandleJoin(셸 UI를 통한 참가에 해당) 중 하나와 일치하면, URI의 쿼리 문자열을 구문 분석합니다. 이 문자열은 키/값 쌍이 있는 일반 URI 쿼리 문자열로 형식화되어 있으며, 다음 필드를 추출합니다.
   • 수락된 초대의 경우:
     1. handle
     2. invitedXuid
     3. senderXuid
   • 참가의 경우:
     1. handle
     2. joinerXuid
     3. joineeXuid
4. 타이틀의 멀티플레이어 코드를 시작합니다. 여기에는 XblMultiplayerSetSubscriptionsEnabled 호출이 포함되어야 합니다.
5. XblMultiplayerSessionCreateHandle을 호출하여 로컬 XblMultiplayerSessionHandle 객체를 만듭니다.
6. XblMultiplayerSessionJoin을 호출하여 세션에 참가합니다. 참가가 활성 상태로 설정되도록 다음 매개 변수 설정을 사용합니다.
   • memberCustomConstantsJson = null
   • initializeRequested = false
   • joinWithActiveStatus = true
7. XblMultiplayerSessionSetSessionChangeSubscription을 호출하여 참가 후 세션이 변경될 때 숄더 탭을 받도록 합니다.
8. 3단계에서 설명한 대로 획득한 핸들을 사용하여 XblMultiplayerWriteSessionByHandleAsync를 호출합니다. 이제 사용자는 세션의 구성원이며, 세션의 데이터를 사용하여 게임에 연결할 수 있습니다.

​

사용자의 현재 액티비티 설정

​

MPSD 세션 업데이트

1. 예를 들어 XblMultiplayerSessionLeave 호출과 같이 필요에 따라 현재 세션을 변경합니다.
2. 모든 변경이 완료되면 다음 메서드 중 하나를 사용하여 로컬 변경 사항을 MPSD에 씁니다.
   • XblMultiplayerWriteSessionAsync
   • XblMultiplayerWriteSessionByHandleAsync
   다른 타이틀도 수정할 수 있는 공유 부분에 쓰는 경우 쓰기 모드를 XblMultiplayerSessionWriteMode::SynchronizedUpdate로 설정합니다. 자세한 내용은 Multiplayer Session Directory 개요 항목의 세션 업데이트 동기화 섹션을 참조하세요. write 메서드는 서버에 참가를 쓰고 최신 세션을 가져와서 다른 세션 구성원과 해당 콘솔의 보안 디바이스 주소(SDA)를 검색합니다. 이러한 콘솔 간에 네트워크 연결을 설정하는 방법에 대한 자세한 내용은 XBOX One의 Winsock 소개를 참조하세요.
3. 이전 로컬 세션 객체를 폐기합니다. 향후 작업이 최신의 알려진 세션 상태를 기반으로 하도록 새로 검색된 세션 객체를 사용합니다.

​

MPSD 세션 나가기

1. 게임 세션에 대해 XblMultiplayerSessionLeave를 호출합니다.
2. 이 항목의 MPSD 세션 업데이트 섹션에 설명된 대로 MPSD의 게임 세션을 업데이트합니다.
3. 필요한 경우 로비 세션에 대해 XblMultiplayerSessionLeave 메서드를 호출한 다음, 해당 세션을 업데이트합니다.
4. 로비 세션에 필요한 경우, XblMultiplayerRemoveSubscriptionLostHandler 및 XblMultiplayerRemoveSessionChangedHandler를 호출하여 등록을 해제함으로써 멀티플레이어 API를 종료합니다.

​

매치메이킹 중 열려 있는 세션 슬롯 채우기

1. 매치메이킹 중에 생성된 티켓 세션의 최신 세션 상태에 액세스합니다.
2. 로비 세션에서 게임 플레이에 사용할 수 있는 플레이어를 추가합니다.
3. 티켓 세션이 가득 찼는지 확인합니다.
4. 세션이 가득 찼다면 게임 플레이를 계속합니다.
5. 세션이 아직 가득 차지 않았다면 이 항목의 매치 티켓 생성에 설명된 대로 매치 티켓을 생성합니다. preserveSession 매개 변수를 Always로 설정하여 티켓을 생성해야 합니다.
6. 매치메이킹을 계속합니다. 자세한 내용은 매치메이킹 개요를 참조하세요.

​

매치 티켓 생성

1. 티켓 세션에 대한 참조를 전달하여 XblMatchmakingCreateMatchTicketAsync를 호출합니다. 이 메서드는 MPSD에서 티켓 세션을 읽고 세션의 사용자에 대한 매치메이킹을 시작합니다. 내부적으로 이 메서드는 POST (/serviceconfigs/{scid}/hoppers/{hoppername})을 호출합니다.
2. 매치메이킹 서비스가 세션의 구성원을 새 세션 또는 다른 기존 세션에 매치시키려는 경우 preserveSession 매개 변수를 Never로 설정합니다. 타이틀이 기존 게임 세션을 티켓 세션으로 재사용하여 게임 플레이를 계속하도록 하려면 preserveSession 매개 변수를 Always로 설정합니다. 그러면 매치메이킹 서비스가 제출된 세션이 유지되도록 하고, 매치된 플레이어를 해당 세션에 추가하도록 할 수 있습니다.
3. CreateMatchTicketResponse 객체에서 반환되는 XblCreateMatchTicketResponse::EstimatedWaitTime을 사용하여 매치메이킹 시간에 대한 사용자 기대치를 설정합니다.
4. 필요한 경우 응답 객체에서 반환되는 XblCreateMatchTicketResponse::MatchTicketId를 사용하여 티켓을 삭제함으로써 세션에 대한 매치메이킹을 취소합니다. 티켓 삭제는 XblMatchmakingDeleteMatchTicketAsync를 사용합니다.

​

매치 티켓 상태 가져오기

1. 티켓 세션에 대한 XblMultiplayerSessionHandle 객체를 얻습니다.
2. XblMultiplayerSessionMatchmakingServer를 호출하여 매치메이킹에 사용된 XblMultiplayerMatchmakingServer 객체에 액세스합니다.
3. XblMultiplayerMatchmakingServer 객체를 확인하여 매치메이킹 프로세스의 상태, 세션의 일반적인 대기 시간, 그리고 매치가 발견된 경우 대상 세션 참조를 확인합니다.