멀티플레이어 활동 코드 예시

이 항목은 멀티플레이어 활동 클라이언트 API의 기본 사용을 위한 빠른 시작 안내서입니다. 이 항목에서는 활동 관리, 초대 보내기 및 최근 플레이어 목록에 플레이어 추가에 대해 설명합니다.

활동
최근 플레이어초대

활동

활동 설정

타이틀이 시작되거나 멀티플레이어 환경에 참여할 때마다 활동을 만들어야 합니다. 이렇게 하면 사용자의 타이틀에 있는 셸과 다른 플레이어의 활동을 함꼐 볼 수 있고, 다른 플레이어가 진행 중인 게임에 참여할 수도 있습니다. 플레이어에서 타이틀에 대한 활동에 참여하고 싶어 하지만 실행 되고 있지 않다면 바로 활성화되고 연결 문자열이 전달됩니다.

타이틀은 플레이어가 참가하거나 떠날 때 활동을 업데이트해야 합니다. 이를 통해 다른 플레이어에게 활동에 대한 보다 풍부한보기를 제공하고 활동이 가득 차면 알립니다.

활동 필드에 대한 정보는 활동 내용을 참조하세요.

활동을 설정하는 코드 예제는 다음과 같습니다. 활동 생성 및 기존 활동 업데이트에 적용됩니다.

auto async = std::make_unique<XAsyncBlock>();
async->queue = queue;
async->callback = [](XAsyncBlock* async)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // Take ownership of XAsyncBlock.
    HRESULT hr = XAsyncGetStatus(async, false);
};

XblMultiplayerActivityInfo info{};
info.connectionString = "dummyConnectionString";
info.joinRestriction = XblMultiplayerActivityJoinRestriction::Followed;
info.maxPlayers = 10;
info.currentPlayers = 1;
info.groupId = "dummyGroupId";

HRESULT hr = XblMultiplayerActivitySetActivityAsync(
    xblContext,
    &info,
    false,
    async.get()
);

if (SUCCEEDED(hr))
{
    async.release();
}

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

• XAsyncBlock
• XAsyncGetStatus
• XblMultiplayerActivityInfo
• XblMultiplayerActivityJoinRestriction
• XblMultiplayerActivitySetActivityAsync

이 항목의 맨 위쪽으로 돌아갑니다.

활동 받기

타이틀은 다른 플레이어의 활동을 알고 싶을 수 있습니다. 예를 들어, 타이틀은 활동과 함께 타이틀에 플레이어 친구의 게임 내 UI를 표시할 수 있습니다.

활동을 검색하는 코드 예제는 다음과 같습니다.

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

    size_t resultSize{};
    HRESULT hr = XblMultiplayerActivityGetActivityResultSize(async, &resultSize);
    if (SUCCEEDED(hr))
    {
        std::vector<uint8_t> buffer(resultSize);
        XblMultiplayerActivityInfo* activityInfo{};
        size_t resultCount{};
        hr = XblMultiplayerActivityGetActivityResult(async, buffer.size(), buffer.data(), &activityInfo, &resultCount, nullptr);
        if (SUCCEEDED(hr))
        {
            // ...
        }
    }
};

HRESULT hr = XblMultiplayerActivityGetActivityAsync(
    xblContext,
    &xuid,
    1,
    async.get()
);

if (SUCCEEDED(hr))
{
    async.release();
}

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

• XAsyncBlock
• XblMultiplayerActivityGetActivityResultSize
• XblMultiplayerActivityInfo
• XblMultiplayerActivityGetActivityResult
• XblMultiplayerActivityGetActivityAsync

이 항목의 맨 위쪽으로 돌아갑니다.

활동 삭제

플레이어가 멀티플레이어 활동을 종료하거나 떠날 때 타이틀은 다음 코드를 사용하여 활동을 삭제해야 합니다.

auto async = std::make_unique<XAsyncBlock>();
async->queue = queue;
async->callback = [](XAsyncBlock* async)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // Take ownership of XAsyncBlock.
    HRESULT hr = XAsyncGetStatus(async, false);
};

HRESULT hr = XblMultiplayerActivityDeleteActivityAsync(xblContext, async.get());

if (SUCCEEDED(hr))
{
    async.release();
}

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

• XAsyncBlock
• XAsyncGetStatus
• XblMultiplayerActivityDeleteActivityAsync

이 항목의 맨 위쪽으로 돌아갑니다.

초대

UI 없이 초대 보내기

플레이어는 한 명 이상의 다른 플레이어에게 직접 초대를 보낼 수 있습니다. 초대를 보내기 전에 타이틀에 활동이 설정되어 있는지 확인해야 합니다. 이렇게하면 셸이 현재 활동을 기반으로 초대를 보내므로 셸과 타이틀 사이에 연속성이 보장됩니다.

UI 없이 초대를 보내려면 XblMultiplayerActivitySetActivityAsync(위의 예 참조)를 사용하여 활동을 설정한 후 제목에서 초대할 플레이어 배열과 함께 XblMultiplayerActivitySendInvitesAsync API를 호출해야 합니다. 현재 활동에서 사용되는 것과 동일한 연결 문자열입니다.

초대의 콘텐츠에 대한 자세한 내용은 멀티 플레이어 환경에 참가하도록 다른 플레이어에 대한 요청 보내기를 참조하세요..

UI 없이 초대장을 보내는 코드 예제는 다음과 같습니다.

auto async = std::make_unique<XAsyncBlock>();
async->queue = queue;
async->callback = [](XAsyncBlock* async)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // Take ownership of XAsyncBlock.
    HRESULT hr = XAsyncGetStatus(async, false);
};

HRESULT hr = XblMultiplayerActivitySendInvitesAsync(
    xblContext,
    &xuid,
    1,
    true, // Setting false will send the invite to only players on the sender's platform.
    "dummyConnectionString",
    async.get()
);

if (SUCCEEDED(hr))
{
    async.release();
}

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

• XAsyncBlock
• XAsyncGetStatus
• XblMultiplayerActivitySendInvitesAsync

UI로 초대장 보내기

플레이어는 한 명 이상의 다른 플레이어에게 직접 초대를 보낼 수 있습니다. 초대를 보내기 전에 타이틀에 활동이 설정되어 있는지 확인해야 합니다. 이렇게하면 셸이 현재 활동을 기반으로 초대를 보내므로 셸과 타이틀 사이에 연속성이 보장됩니다.

UI가 포함된 초대를 보내려면 XblMultiplayerActivitySetActivityAsync(위의 예 참조)를 사용하여 활동을 설정한 후 제목에서 요청하는 사용자를 따라 전달되는 XGameUiShowMultiplayerActivityGameInviteAsync API를 호출해야 합니다. 타이틀의 현재 활동을 사용하고 연결 문자열과 설정을 사용하여 플레이어를 초대합니다.

초대의 콘텐츠에 대한 자세한 내용은 멀티 플레이어 환경에 참가하도록 다른 플레이어에 대한 요청 보내기를 참조하세요..

UI로 초대장을 보내는 코드 예는 다음과 같습니다.

auto async = std::make_unique<XAsyncBlock>();
async->queue = queue;
async->callback = [](XAsyncBlock* async)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // Take ownership of XAsyncBlock.
    HRESULT hr = XGameUiShowMultiplayerActivityGameInviteResult(async);
    if (hrAsync == S_OK) 
    { 
        // Handle success 
    } 
    else 
    { 
        // Likely will only happen during development - usually indicates 
        // an invalid user was passed in or that there is no multiplayer activity set
    }     
};

HRESULT hr = XGameUiShowMultiplayerActivityGameInviteAsync(
    async.get()
    requestingUser
);

if (SUCCEEDED(hr))
{
    async.release();
}

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

• XAsyncBlock
• XAsyncGetStatus
• XGameUiShowMultiplayerActivityGameInviteAsync
• XGameUiShowMultiplayerActivityGameInviteResult

이 항목의 맨 위쪽으로 돌아갑니다.

초대 받기

플레이어가 초대를 수락했을 때 알림을 받으려면 XGameInviteRegisterForEvent을(를) 사용하여 타이틀을 초대 알림에 등록할 수 있습니다. 초대가 수락될 때마다 형식화된 URI가 등록된 콜백을 통해 타이틀로 전달됩니다. URI를 구문 분석하여 초대 보낸 사람, 받는 사람 및 연결 문자열을 확인할 수 있습니다. 연결 문자열은 타이틀에 따라 다르며 멀티플레이어 활동이 생성될 때 설정됩니다. 멀티플레이어 활동 서비스를 사용하는 타이틀의 경우 URI의 전체 형식이 다음 표에 나와 있습니다.

플랫폼	형식
콘솔의 Microsoft GDK(게임 개발 키트) 또는 Xbox One 소프트웨어 개발 키트	ms-xbl-<titleId>://inviteAccept?invitedUser=<xuid>&sender=<xuid>&connectionString=<connectionString>
PC의 Microsoft GDK(게임 개발 키트) 또는 UWP(유니버설 Windows 플랫폼)	ms-xbl-multiplayer://inviteAccept?invitedUser=<xuid>&sender=<xuid>&connectionString=<connectionString>

초대 알림이 더 이상 필요하지 않은 경우 XGameInviteUnregisterForEvent을(를) 사용하여 콜백을 등록 취소할 수 있습니다. 수락된 초대를 등록하고 처리하는 코드 예제는 다음과 같습니다.

void CALLBACK MyXGameInviteEventCallback(
    _In_opt_ void* context,
    _In_ const char* inviteUri)
{
    if (inviteUri != nullptr)
    {
        std::string uri{ inviteUri };
        size_t invitedUserBegin = uri.find("invitedUser=");
        size_t senderBegin = uri.find("sender=");
        std::string invitedUser = uri.substr(invitedUserBegin, uri.find('&', invitedUserBegin) - invitedUserBegin);
        std::string sender = uri.substr(senderBegin, uri.find('&', senderBegin) - senderBegin);
        std::string connectionString = uri.substr(uri.find("connectionString="));

        // ...
    }
}

XTaskQueueRegistrationToken token = { 0 };
HRESULT hr = XGameInviteRegisterForEvent(
    queue,
    nullptr,
    MyXGameInviteEventCallback,
    &token
    );

// ...
bool result = XGameInviteUnregisterForEvent(token, true);

자세한 내용은 다음을 참조하십시오.

• XGameInviteRegisterForEvent
• XGameInviteUnregisterForEvent

이 항목의 맨 위쪽으로 돌아갑니다.

최근 플레이어

플레이어의 최근 플레이어 목록을 업데이트하려면 타이틀에서 현재 플레이어와 의미있는 상호 작용을 한 다른 플레이어 목록을 제출해야 합니다. 목록은 단방향이므로 각 플레이어의 클라이언트가 자신의 목록을 업데이트해야 하며 플레이어 목록은 서로의 목록에 영향을 주지 않습니다.

예를 들어, 한 그룹의 플레이어가 게임 전 로비에 함께 있고 서로 일치한다고 가정합니다. 각 플레이어는 경기가 시작될 때 로비에있는 다른 모든 xuids(으)로 목록을 업데이트합니다. 새로운 플레이어가 참여하면 해당 플레이어는 개별적으로 작성할 수 있습니다.

참고 항목

의미 있는 상호 작용을 정의하는 항목을 결정할 수 있습니다. 한 타이틀에서는 로비에 있을 수 있습니다. 다른 타이틀에서는 다른 플레이어를 쏘는 플레이어가 될 수 있습니다. 세 번째 타이틀에서는 단순히 다른 플레이어가 화면에 표시되는 경우가 될 수 있습니다.

매치 세션이 시작될 때까지 플레이어 팀이 보이지 않게 하려면 보이게 하고 싶은 시점까지 플레이어 목록 작성을 미뤄도 됩니다. 클라이언트 쪽 최근 플레이어 목록을 플러시할 때 즉시 강제 플러시가 필요하다면 XblMultiplayerActivityFlushRecentPlayersAsync을 호출할 수 있습니다. 그 외에는 최근 플레이어 목록이 자동으로 5초 마다 플러시됩니다.

최신 플레이어 업데이트 목록과 업데이트를 플러시하는 코드의 예가 아래에 나와 있습니다.

최근 플레이어 업데이트

XblMultiplayerActivityRecentPlayerUpdate update{ xuid };
HRESULT hr = XblMultiplayerActivityUpdateRecentPlayers(xblContext, &update, 1);

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

• XblMultiplayerActivityRecentPlayerUpdate
• XblMultiplayerActivityUpdateRecentPlayers

이 항목의 맨 위쪽으로 돌아갑니다.

최근 플레이어 플러시

auto async = std::make_unique<XAsyncBlock>();
async->queue = queue;
async->callback = [](XAsyncBlock* async)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // Take ownership of XAsyncBlock.
    HRESULT hr = XAsyncGetStatus(async, false);
};

HRESULT hr = XblMultiplayerActivityFlushRecentPlayersAsync(xblContext, async.get());
if (SUCCEEDED(hr))
{
    async.release();
}

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

• XAsyncBlock
• XAsyncGetStatus
• XblMultiplayerActivityFlushRecentPlayersAsync

이 항목의 맨 위쪽으로 돌아갑니다.