Jogar multiplayer com amigos usando o Multiplayer Manager

Em um cenário multiplayer simples, um jogador do seu jogo pode jogá-lo online com amigos. Este tópico descreve as etapas básicas que você precisa implementar para oferecer suporte a esse cenário usando o Multiplayer Manager.

Etapas para enviar e aceitar um convite

As etapas a seguir usam o Multiplayer Manager para enviar um convite a um amigo do usuário para que esse amigo possa ingressar em um jogo em andamento.

Inicializar o Multiplayer Manager
Criar a sessão de lobby adicionando usuários locais
Enviar convites para amigos
Aceitar convites
Ingressar em uma sessão de jogo a partir do lobby

As etapas 1, 2, 3 e 5 são realizadas no dispositivo que está enviando o convite. A etapa 4 normalmente é iniciada no dispositivo do convidado, após a inicialização do aplicativo por meio da ativação de protocolo. Para obter mais informações, consulte Jogando com amigos (fluxograma).

Inicializar o Multiplayer Manager

O objeto da sessão de lobby é criado automaticamente quando o Multiplayer Manager é inicializado com um nome de modelo de sessão válido. Os modelos de sessão são definidos na configuração do serviço.

A instância da sessão de lobby no serviço não é criada até que um usuário seja adicionado.

API C simples

HRESULT hr = XblMultiplayerManagerInitialize(lobbySessionTemplateName, queueUsedByMultiplayerManager);

Para obter mais informações, consulte XblMultiplayerManagerInitialize. Voltar ao início deste tópico.

Criar a sessão de lobby adicionando usuários locais

Adicione os usuários dos serviços do XBOX conectados localmente à sessão de lobby. Um novo lobby é hospedado quando o primeiro usuário é adicionado. Todos os outros usuários são adicionados ao lobby existente como usuários secundários. O Multiplayer Manager divulga o lobby no shell para que os amigos possam ingressar. Você só pode enviar convites, definir propriedades do lobby e acessar os membros do lobby por meio de lobby() depois de adicionar o usuário local. Quando um usuário local ingressa no lobby, recomendamos definir o endereço de conexão dele e quaisquer propriedades personalizadas. Você deve repetir esse processo para todos os usuários conectados localmente. Voltar ao início deste tópico.

Adicionar um único usuário local

API C simples

HRESULT hr = XblMultiplayerManagerLobbySessionAddLocalUser(xblUserHandle);

if (!SUCCEEDED(hr))
{
    // Handle failure.
}

// Set member connection address.
const char* connectionAddress = "1.1.1.1";
hr = XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress(
    xblUserHandle, connectionAddress, context);

if (!SUCCEEDED(hr))
{
    // Handle failure.
}

// Set custom member properties.
const char* propName = "Name";
const char* propValueJson = "{}";
hr = XblMultiplayerManagerLobbySessionSetProperties(propName, propValueJson, context);

if (!SUCCEEDED(hr))
{
    // Handle failure.
}
...

Para obter mais informações, consulte:

Voltar ao início deste tópico.

Adicionar vários usuários locais

API C simples

std::vector<XblUserHandle> xblUsers;
for (XblUserHandle xblUserHandle : xblUsers)
{
    HRESULT hr = XblMultiplayerManagerLobbySessionAddLocalUser(xblUserHandle);

    if (!SUCCEEDED(hr))
    {
        // Handle failure.
    }

    // Set member connection address.
    const char* connectionAddress = "1.1.1.1";
    hr = XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress(
        xblUserHandle, connectionAddress, context);

    if (!SUCCEEDED(hr))
    {
        // Handle failure.
    }

    // Set custom member properties.
    const char* propName = "Name";
    const char* propValueJson = "{}";
    hr = XblMultiplayerManagerLobbySessionSetProperties(propName, propValueJson, context);
    ...
}

Para obter mais informações, consulte:

As alterações são agrupadas na próxima chamada de XblMultiplayerManagerDoWork. O Multiplayer Manager dispara um evento XblMultiplayerEventType::UserAdded sempre que um usuário é adicionado à sessão de lobby. Recomendamos verificar o código de erro do evento para saber se o usuário foi adicionado com êxito. Em caso de falha, uma mensagem de erro fornece detalhes sobre os motivos da falha. O Multiplayer Manager executa as funções a seguir para criar a sessão de lobby adicionando usuários locais.

Registra assinaturas do Real-Time Activity e do multiplayer no serviço multiplayer dos serviços do XBOX.
Cria a sessão de lobby.
Adiciona todos os jogadores locais como ativos.
Carrega o endereço de dispositivo seguro (SDA).
Define as propriedades dos membros.
Registra-se para eventos de alteração de sessão.
Define a sessão de lobby como uma sessão ativa.

Voltar ao início deste tópico.

Enviar convites para amigos

Exiba a interface do usuário padrão do XBOX, na qual o jogador pode selecionar amigos ou jogadores recentes para convidar para o jogo. Quando o jogador confirma a seleção, o Multiplayer Manager envia os convites aos jogadores selecionados. Os jogos também podem usar o método XblMultiplayerManagerLobbySessionInviteUsers para enviar convites a um conjunto de pessoas definidas por seus IDs de usuário dos serviços do XBOX. Esse método é útil se você usar sua própria interface do usuário no jogo em vez da interface do usuário padrão do XBOX.

API C simples

size_t xuidsCount = 1;
uint64_t xuids[1] = {};
xuids[0] = 1234567891234567;
HRESULT hr = XblMultiplayerManagerLobbySessionInviteUsers(
    xblUserHandle, 
    xuids, 
    xuidsCount, 
    nullptr,    // ContextStringId 
    nullptr     // CustomActivationContext
);

Para obter mais informações, consulte XblMultiplayerManagerLobbySessionInviteUsers. O Multiplayer Manager executa as funções a seguir para enviar convites aos amigos.

Exibe a Title-Callable UI (TCUI) padrão do XBOX
Envia um convite diretamente aos jogadores selecionados

Voltar ao início deste tópico.

Aceitar convites

Quando um jogador convidado aceita um convite de jogo ou ingressa no jogo de um amigo por meio de uma interface do usuário do shell, o jogo é iniciado no dispositivo dele. Em jogos baseados no Microsoft Game Development Kit (GDK), depois que o jogo for iniciado, escute os eventos de convite chamando XGameActivationRegisterForEvent. Em jogos baseados no XBOX One Software Development Kit e na Plataforma Universal do Windows (UWP), depois que o jogo for iniciado, o Multiplayer Manager pode usar os argumentos do evento de ativação de protocolo para ingressar no lobby. Se o usuário convidado não for adicionado por meio de XblMultiplayerManagerLobbySessionAddLocalUser, XblMultiplayerManagerJoinLobby falhará e fornecerá o xuid para o qual o convite foi enviado ao chamar XblMultiplayerEventArgsXuid com o evento JoinLobbyCompleted. Depois de ingressar no lobby, recomendamos definir o endereço de conexão do membro local e quaisquer propriedades personalizadas do membro. Você também pode definir o host por meio de XblMultiplayerManagerLobbySessionSetSynchronizedHost, caso não exista um. Por fim, o Multiplayer Manager adiciona automaticamente o usuário à sessão de jogo, se um jogo já estiver em andamento e houver espaço para o convidado. O título é notificado por meio do evento JoinGameCompleted, que fornece um código de erro e uma mensagem apropriados. Os resultados de erro ou de êxito são tratados por meio do evento JoinLobbyCompleted.

API C simples

void CALLBACK MyXGameInviteEventCallback(
    _In_opt_ void* context,
    _In_ const XGameActivationInfo* activationInfo)
{
    UNREFERENCED_PARAMETER(context);
    if (activationInfo->type == XGameActivationType::AcceptedGameInvite)
    {
        if (activationInfo->inviteUri != nullptr)
        {
            std::string inviteString(activationInfo->inviteUri);
            auto pos = inviteString.find("handle=");
            auto inviteHandleId = inviteString.substr(pos + 7, 36);

            // Now use inviteHandleId when calling XblMultiplayerManagerJoinLobby().  
            // See the example call as follows.
        }
    }
}

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

HRESULT hr = XblMultiplayerManagerJoinLobby(inviteHandleId, xblUserHandle);
if (!SUCCEEDED(hr))
{
    // Handle failure.
}

// Set member connection address.
const char* connectionAddress = "1.1.1.1";
hr = XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress(
    xblUserHandle, connectionAddress, context);

Para obter mais informações, consulte:

O Multiplayer Manager executa as funções a seguir para aceitar convites.

Registra assinaturas do Real-Time Activity e do multiplayer.
Ingressa na sessão de lobby.
Limpa o estado existente do lobby.
Adiciona todos os jogadores locais como ativos.
Carrega o SDA.
Define as propriedades dos membros.
Registra-se para eventos de alteração de sessão.
Define a sessão de lobby como a sessão ativa.
Ingressa na sessão de jogo (se houver).
Usa um identificador de transferência.

Voltar ao início deste tópico.

Ingressar em uma sessão de jogo a partir do lobby

Depois que os convites forem aceitos e o host estiver pronto para começar a jogar, você poderá iniciar um novo jogo que inclua os membros da sessão de lobby chamando XblMultiplayerManagerJoinGameFromLobby. Os resultados de erro ou de êxito são tratados por meio do evento JoinGameCompleted.

API C simples

HRESULT hr = XblMultiplayerManagerJoinGameFromLobby(gameSessionTemplateName);
if (!SUCCEEDED(hr))
{
    // Handle error.
}

Para obter mais informações, consulte XblMultiplayerManagerJoinGameFromLobby. O Multiplayer Manager executa as funções a seguir para ingressar em uma sessão de jogo a partir do lobby.

Cria a sessão de jogo.
Adiciona todos os jogadores locais como ativos.
Carrega o SDA.
Define as propriedades dos membros.
Registra-se para eventos de alteração de sessão.
Divulga o jogo por meio da sessão de lobby.

Voltar ao início deste tópico.

XBOX Services

PlayFab

Jogar multiplayer com amigos usando o Multiplayer Manager

Etapas para enviar e aceitar um convite

Inicializar o Multiplayer Manager

API C simples

Criar a sessão de lobby adicionando usuários locais

Adicionar um único usuário local

API C simples

Adicionar vários usuários locais

API C simples

Enviar convites para amigos

API C simples

Aceitar convites

API C simples

Ingressar em uma sessão de jogo a partir do lobby

API C simples

​Etapas para enviar e aceitar um convite

​Inicializar o Multiplayer Manager

​API C simples

​Criar a sessão de lobby adicionando usuários locais

​Adicionar um único usuário local

​API C simples

​Adicionar vários usuários locais

​API C simples

​Enviar convites para amigos

​API C simples

​Aceitar convites

​API C simples

​Ingressar em uma sessão de jogo a partir do lobby

​API C simples

Etapas para enviar e aceitar um convite

Inicializar o Multiplayer Manager

API C simples

Criar a sessão de lobby adicionando usuários locais

Adicionar um único usuário local

API C simples

Adicionar vários usuários locais

API C simples

Enviar convites para amigos

API C simples

Aceitar convites

API C simples

Ingressar em uma sessão de jogo a partir do lobby

API C simples