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

# Jogar multiplayer com amigos usando o Multiplayer Manager

> Guia passo a passo para usar o Multiplayer Manager para inicializar uma sessão de lobby, enviar convites do XBOX Live e permitir que amigos ingressem em um jogo em andamento.

<a id="top" />

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.

1. [Inicializar o Multiplayer Manager](#initialize-multiplayer-manager)
2. [Criar a sessão de lobby adicionando usuários locais](#create-lobby)
3. [Enviar convites para amigos](#send-invites)
4. [Aceitar convites](#accept-invites)
5. [Ingressar em uma sessão de jogo a partir do lobby](#join-game)

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)](/pt-BR/services/xbox-services/multiplayer/mpm/concepts/flowcharts/live-mpm-play-with-friends).

## Inicializar o Multiplayer Manager <a id="initialize-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.

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

#### API C simples

```cpp theme={null}
HRESULT hr = XblMultiplayerManagerInitialize(lobbySessionTemplateName, queueUsedByMultiplayerManager);
```

Para obter mais informações, consulte [XblMultiplayerManagerInitialize](/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerinitialize).

[Voltar ao início deste tópico.](#top)

## Criar a sessão de lobby adicionando usuários locais <a id="create-lobby" />

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.](#top)

### Adicionar um único usuário local

#### API C simples

```cpp theme={null}
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:

* [XblMultiplayerManagerLobbySessionAddLocalUser](/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionaddlocaluser)
* [XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress](/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionsetlocalmemberconnectionaddress)
* [XblMultiplayerManagerLobbySessionSetProperties](/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionsetproperties)

[Voltar ao início deste tópico.](#top)

### Adicionar vários usuários locais

#### API C simples

```cpp theme={null}
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:

* [XblMultiplayerManagerLobbySessionAddLocalUser](/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionaddlocaluser)
* [XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress](/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionsetlocalmemberconnectionaddress)
* [XblMultiplayerManagerLobbySessionSetProperties](/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionsetproperties)

As alterações são agrupadas na próxima chamada de [XblMultiplayerManagerDoWork](/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork).
O Multiplayer Manager dispara um evento [XblMultiplayerEventType](/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/enums/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.](#top)

## Enviar convites para amigos <a id="send-invites" />

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](/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/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

```cpp theme={null}
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](/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/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.](#top)

## Aceitar convites <a id="accept-invites" />

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](/pt-BR/reference/system/xgameactivation/functions/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](/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionaddlocaluser), [XblMultiplayerManagerJoinLobby](/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoinlobby) falhará e fornecerá o xuid para o qual o convite foi enviado ao chamar [XblMultiplayerEventArgsXuid](/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/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](/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/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

```cpp theme={null}

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);

```

```cpp theme={null}
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:

* [XblMultiplayerManagerJoinLobby](/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoinlobby)
* [XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress](/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionsetlocalmemberconnectionaddress)

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.](#top)

## Ingressar em uma sessão de jogo a partir do lobby <a id="join-game" />

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](/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoingamefromlobby).

Os resultados de erro ou de êxito são tratados por meio do evento `JoinGameCompleted`.

#### API C simples

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

Para obter mais informações, consulte [XblMultiplayerManagerJoinGameFromLobby](/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/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.](#top)


## Related topics

- [Enviando convites de jogo usando o Multiplayer Manager](/pt-BR/services/xbox-services/multiplayer/mpm/how-to/live-send-game-invites.md)
- [Tratar a ativação de protocolo com o Multiplayer Manager](/pt-BR/services/xbox-services/multiplayer/mpm/how-to/live-handle-protocol-activation.md)
- [Matchmaking multiplayer com SmartMatch e MPM](/pt-BR/services/xbox-services/multiplayer/mpm/how-to/live-play-multiplayer-with-matchmaking.md)
- [Código de exemplo do Multiplayer Manager](/pt-BR/services/xbox-services/multiplayer/mpm/how-to/live-mm-howto-nav.md)
- [Cenários multijogador comuns](/pt-BR/services/xbox-services/multiplayer/overviews/live-common-multiplayer-scenarios.md)