Habilitar a busca de um jogo multiplayer usando SmartMatch com o Multiplayer Manager

Este tópico descreve as etapas básicas necessárias para implementar o matchmaking SmartMatch usando o Multiplayer Manager. Um jogador pode não ter amigos suficientes online quando quer jogar, ou pode simplesmente querer jogar contra jogadores aleatórios online. Você pode usar o serviço SmartMatch para encontrar outros jogadores do XBOX.

Encontrar uma partida

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

Inicializar o Multiplayer Manager
Criar a sessão de lobby adicionando usuários locais
Enviar convites para amigos (opcional)
Aceitar convites (opcional)
Encontrar uma partida

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 usando o matchmaking SmartMatch (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 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.

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 local é 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 (opcional)

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 jogadores definidos 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 (opcional)

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 usando a ativação de protocolo. 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 adicionará 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

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.

Encontrar uma partida

Depois que os convites forem aceitos e o host estiver pronto para começar a jogar, você poderá usar o SmartMatch para fazer uma das seguintes ações:

Encontrar um jogo existente que tenha vagas abertas suficientes para todos os membros da sessão de lobby chamando XblMultiplayerManagerFindMatch.
Criar uma nova sessão de jogo que inclua todos os membros da sessão de lobby e preencher as vagas abertas com outros jogadores que estão procurando uma partida do mesmo tipo de jogo, chamando XblMultiplayerManagerJoinGameFromLobby seguido de XblMultiplayerManagerAutoFillMembersDuringMatchmaking.

Antes de chamar XblMultiplayerManagerFindMatch, você deve primeiro configurar os hoppers na configuração do serviço. Um hopper define as regras que o SmartMatch usa para combinar jogadores.

API C simples

uint32_t timeoutInSeconds = 30;
HRESULT hr = XblMultiplayerManagerFindMatch(hopperName, attributesJson, timeoutInSeconds);
if (!SUCCEEDED(hr))
{
    // Handle failure.
}

Para obter mais informações, consulte XblMultiplayerManagerFindMatch. O Multiplayer Manager executa as funções a seguir para encontrar uma partida.

Cria um tíquete de partida.
Trata todos os estágios de qualidade de serviço (QoS).
Trata as alterações na lista de jogadores.
Reenvia (se necessário).
Ingressa na sessão de jogo de destino.
Divulga o jogo por meio da sessão de lobby.

Voltar ao início deste tópico.

XBOX Services

PlayFab

Habilitar a busca de um jogo multiplayer usando SmartMatch com o Multiplayer Manager

Encontrar uma partida

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 (opcional)

API C simples

Aceitar convites (opcional)

API C simples

Encontrar uma partida

API C simples

​Encontrar uma partida

​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 (opcional)

​API C simples

​Aceitar convites (opcional)

​API C simples

​Encontrar uma partida

​API C simples

Encontrar uma partida

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 (opcional)

API C simples

Aceitar convites (opcional)

API C simples

Encontrar uma partida

API C simples