> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Visão geral do Multiplayer Manager

> Visão geral do Multiplayer Manager, a API de alto nível do XBOX Live que simplifica o gerenciamento de sessões do MPSD, o matchmaking SmartMatch, os convites e a entrada em andamento.

Este tópico descreve a API de alto nível para adicionar funcionalidade multiplayer gerenciando sessões, matchmaking e convites de jogo. A API fornece um modelo de programação baseado em estado e um baseado em eventos.

Os serviços do XBOX oferecem amplo suporte para adicionar funcionalidade multiplayer aos seus títulos, para que seu jogo possa conectar membros do XBOX em todo o mundo.
Isso inclui cenários avançados de matchmaking, a possibilidade de um jogador ingressar no jogo em andamento de um amigo e muito mais.

Implementar o multiplayer dos serviços do XBOX usando diretamente as APIs Multiplayer pode ser uma tarefa complexa. Isso exige bastante design e testes para verificar se você está seguindo as práticas recomendadas e atendendo aos requisitos de certificação.

O Multiplayer Manager facilita a adição de funcionalidade multiplayer ao seu jogo gerenciando sessões e matchmaking e fornecendo um modelo de programação baseado em estado e um baseado em eventos.

O Multiplayer Manager é um conjunto de APIs. Elas foram projetadas para facilitar a implementação de cenários multiplayer em jogos dos serviços do XBOX com designs multiplayer hospedados por pares.

O Multiplayer Manager fornece uma API centrada em cenários multiplayer comuns, como jogar jogos multiplayer com amigos, tratar convites de jogo, tratar a entrada em andamento, matchmaking e muito mais.

O Multiplayer Manager oferece suporte a vários usuários locais. Ele também facilita a integração do seu título com o Multiplayer Session Directory (MPSD) se você estiver usando um serviço de matchmaking de terceiros. Muitos desses cenários podem ser realizados com apenas algumas chamadas de API.

## Principais recursos

Os principais recursos da API do Multiplayer Manager são os seguintes.

* Gerenciamento de sessões e matchmaking dos serviços do XBOX simplificados
* Modelo de programação baseado em estado e em eventos
* Garante as práticas recomendadas dos serviços do XBOX, além de estar em conformidade com os XRs de Multiplayer
* Implementa os fluxogramas do Multiplayer 2015

Informações importantes sobre o design da API do Multiplayer Manager são as seguintes.

* Sessões grandes do MPSD (mais de 100 membros) não são compatíveis.
* Destina-se apenas a designs multiplayer hospedados por pares. Títulos com servidores dedicados devem usar o [serviço Multiplayer Activity](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/mpa/live-mpa-overview.md) ou as [APIs do serviço Multiplayer](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/mpsd/live-mpsd-overview.md) e [chamadas de serviço para serviço (tópico sob NDA)](https://docs.xbox.com/pt-BR/services/xbox-services/fundamentals/s2s-auth-calls/s2s-calls/live-title-service-calls-xbox-live.md).

> [!NOTE]
>
> Para passar na certificação, seu jogo ainda precisa implementar os eventos obrigatórios para o multiplayer online.

## Visão geral

O Multiplayer Manager se baseia nos principais conceitos a seguir.

* **Sessão de lobby:** uma sessão persistente usada para gerenciar os usuários locais do dispositivo e os amigos convidados que desejam jogar juntos.

  O grupo pode jogar o jogo; por exemplo, várias rodadas, mapas e níveis. A sessão de lobby acompanha esse grupo principal de amigos (incluindo os jogadores locais do dispositivo).
  Normalmente, esse grupo é formado enquanto o host navega pelos menus e conversa com os membros do grupo para decidir qual modo de jogo desejam jogar.

* **Sessão de jogo:** acompanha os jogadores que estão jogando uma instância específica do jogo.

  Por exemplo, uma corrida, um mapa ou um nível.
  Você pode criar uma nova sessão de jogo por meio de [XblMultiplayerManagerJoinGameFromLobby](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoingamefromlobby.md) que inclua os membros da sessão de lobby.

  Quando um membro aceita um convite, ele é adicionado ao lobby e à sessão de jogo (se houver espaço).

  Jogadores adicionais podem ser adicionados à sessão de jogo se o matchmaking estiver habilitado, mas esses jogadores adicionais não são adicionados à sessão de lobby.
  Isso significa que, quando o jogo termina, os jogadores da sessão de lobby continuam juntos, enquanto os jogadores extras do matchmaking não.

* [XblMultiplayerManagerMember](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayermanagermember.md): representa um usuário individual conectado em um dispositivo local ou remoto.

* [XblMultiplayerManagerDoWork](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork.md): garante que as atualizações adequadas do estado do jogo sejam mantidas entre o título e o serviço Multiplayer dos serviços do XBOX.

  Para garantir o melhor desempenho, [XblMultiplayerManagerDoWork](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork.md) deve ser chamado com frequência, por exemplo, uma vez por quadro.

  [XblMultiplayerManagerDoWork](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork.md) fornece uma matriz de eventos de retorno de chamada [XblMultiplayerEvent](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayerevent.md) para o jogo tratar.

## Máquina de estado

A chamada de [XblMultiplayerManagerDoWork](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork.md) é necessária para garantir que seu estado seja mantido atualizado.
Para que o Multiplayer Manager faça seu trabalho, você deve chamar o método [XblMultiplayerManagerDoWork](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork.md) regularmente.
A maneira mais confiável de fazer isso é chamá-lo pelo menos uma vez por quadro.

[XblMultiplayerManagerDoWork](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork.md) retorna rapidamente quando não há trabalho a ser feito, portanto não há motivo para se preocupar em chamá-lo com muita frequência.

### Threading

Nenhum dos objetos retornados pela API do Multiplayer Manager deve ser considerado thread-safe.
No entanto, ela oferece controle para fazer a sincronização de threads se você a estiver chamando de vários threads.

A biblioteca tem proteção interna contra multithreading. No entanto, você ainda precisa implementar seu próprio bloqueio se precisar que um thread acesse quaisquer valores; por exemplo, percorrer a lista de membros enquanto outro thread pode estar invocando [XblMultiplayerManagerDoWork](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork.md).

### Atualização do modelo baseado em estado

O Multiplayer Manager mantém um modelo baseado em estado que atualiza as sessões em segundo plano à medida que os jogadores entram, saem ou quando as sessões são atualizadas.
Para ajudar a evitar problemas de sincronização de threads entre o thread da interface do usuário e o thread do jogo, o Multiplayer Manager não atualiza o estado das sessões visível para o aplicativo até que você chame o método [XblMultiplayerManagerDoWork](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork.md).

Tradicionalmente, você receberia notificações sobre eventos, como alterações de sessão, em um thread em segundo plano e, em seguida, teria que sincronizá-las com um thread da interface do usuário para exibir essas alterações.
Com o Multiplayer Manager, esse trabalho de bastidores é feito para você.

Você pode chamar [XblMultiplayerManagerDoWork](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork.md) no thread principal no momento que escolher para obter o instantâneo mais recente do estado que o Multiplayer Manager está armazenando em buffer para você nos bastidores.

## Eventos e notificações

O Multiplayer Manager define um conjunto de eventos significativos (consulte [XblMultiplayerEvent](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayerevent.md)) e notifica o título por meio do método [XblMultiplayerManagerDoWork](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork.md) quando eles ocorrem.
Por exemplo, os eventos incluem jogadores remotos entrando ou saindo, propriedades de membros mudando ou o estado da sessão mudando.

Todas as APIs do Multiplayer Manager são assíncronas.
O método [XblMultiplayerManagerDoWork](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork.md) retorna uma lista de eventos quando essas operações assíncronas são concluídas.
Seu título deve tratar esses eventos da maneira adequada à sua situação.
Para obter mais detalhes, consulte a documentação da classe [XblMultiplayerEvent](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayerevent.md).

Cada [XblMultiplayerEvent](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayerevent.md) retornado inclui um `EventArgsHandle`, que você deve usar para obter os `args` apropriados para o tipo de evento.
Por exemplo, se o [XblMultiplayerEventType](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/enums/xblmultiplayereventtype.md) for `MemberJoined`, você poderia chamar [XblMultiplayerEventArgsMembersCount](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayereventargsmemberscount.md) e [XblMultiplayerEventArgsMembers](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayereventargsmembers.md).

O exemplo a seguir demonstra o uso de [XblMultiplayerManagerDoWork](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork.md) para tratar eventos.

#### API C simples

```cpp theme={null}
size_t eventCount{ 0 };
const XblMultiplayerEvent* events{ nullptr };
HRESULT hr = XblMultiplayerManagerDoWork(&events, &eventCount);
if (FAILED(hr))
{
    // Handle failure.
}

for (auto i = 0u; i < eventCount; ++i)
{
    switch (events[i].EventType)
    {
        case XblMultiplayerEventType::MemberJoined:
        {
            // Handle MemberJoined.
            size_t memberCount = 0;
            hr = XblMultiplayerEventArgsMembersCount(events[i].EventArgsHandle, &memberCount);
            assert(SUCCEEDED(hr));

            std::vector<XblMultiplayerManagerMember> members(memberCount);
            hr = XblMultiplayerEventArgsMembers(events[i].EventArgsHandle, memberCount, members.data());
            assert(SUCCEEDED(hr));
            ...

            break;
        }

        case XblMultiplayerEventType::SessionPropertyChanged:
        {
            // Handle SessionPropertyChanged.
            const char* changedProperty{ nullptr };
            hr = XblMultiplayerEventArgsPropertiesJson(events[i].EventArgsHandle, &changedProperty);
            assert(SUCCEEDED(hr));
            ...

            break;
        }
        ...
    }
}
```

Para obter mais informações, consulte:

* [XblMultiplayerEvent](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayerevent.md)
* [XblMultiplayerEventArgsMembers](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayereventargsmembers.md)
* [XblMultiplayerEventArgsMembersCount](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayereventargsmemberscount.md)
* [XblMultiplayerEventArgsPropertiesJson](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayereventargspropertiesjson.md)
* [XblMultiplayerEventType](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/enums/xblmultiplayereventtype.md)
* [XblMultiplayerManagerDoWork](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork.md)
* [XblMultiplayerManagerMember](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayermanagermember.md)

## Cenários

Esta seção aborda cenários comuns e as APIs que você chamaria em cada cenário.
Também são fornecidas algumas informações sobre o que o Multiplayer Manager faz nos bastidores.

* [Habilitar jogos multiplayer com amigos usando o Multiplayer Manager](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/mpm/how-to/live-play-multiplayer-with-friends.md)
* [Encontrando um jogo multiplayer usando o SmartMatch com o Multiplayer Manager](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/mpm/how-to/live-play-multiplayer-with-matchmaking.md)
* [Enviando convites de jogo usando o Multiplayer Manager](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/mpm/how-to/live-send-game-invites.md)
* [Tratando a ativação de protocolo para iniciar um jogo usando o Multiplayer Manager](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/mpm/how-to/live-handle-protocol-activation.md)

Para obter uma visão geral de alto nível da API, consulte [Visão geral da API do Multiplayer Manager](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/mpm/concepts/live-multiplayer-manager-api-overview.md).

## O que o Multiplayer Manager não faz

O Multiplayer Manager facilita muito a implementação de cenários multiplayer e abstrai alguns dos dados para você. No entanto, o Multiplayer Manager não trata o seguinte:

* Jogos em servidores online persistentes, como jogos multiplayer massivos online (MMO), ou outros tipos de jogos que exigem sessões grandes (mais de 100 jogadores em uma sessão)
* Gerenciamento de sessões de servidor para servidor
* Limitação de chamadas do MPSD para respeitar a [limitação de taxa refinada](https://docs.xbox.com/pt-BR/services/xbox-services/develop/best-practices/live-fine-grained-rate-limiting.md)
* Mistura das APIs do serviço Multiplayer com as APIs do Multiplayer Manager

> [!NOTE]
>
> O Multiplayer Manager não está restrito a nenhuma tecnologia de rede específica e deve funcionar com qualquer camada de comunicação de rede.

## Recursos

Para obter um exemplo funcional da API, consulte o [exemplo NetRumble](https://aka.ms/gdkdl).

Para obter a documentação da API, consulte [multiplayer\_manager\_c](https://docs.xbox.com/pt-BR/reference/live/xsapi-c/multiplayer_manager_c/multiplayer_manager_c_members.md).
Você também pode consultar o arquivo de cabeçalho `multiplayer_manager_c.h`.

Se você tiver dúvidas, comentários ou problemas ao usar o Multiplayer Manager, entre em contato com seu gerente de contas de desenvolvedor (DAM) ou publique um tópico de suporte nos fóruns em [https://forums.xboxlive.com](https://forums.xboxlive.com).


## Related topics

- [Visão geral do multijogador dos serviços XBOX](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/overviews/live-multiplayer-intro.md)
- [Visão geral da API do Multiplayer Manager](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/mpm/concepts/live-multiplayer-manager-api-overview.md)
- [Visão geral do matchmaking](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/matchmaking/live-matchmaking-overview.md)
- [Visão geral do Social Manager](https://docs.xbox.com/pt-BR/services/xbox-services/community/social-manager/live-social-manager-overview.md)
- [Visão geral do multijogador](https://docs.xbox.com/pt-BR/services/xbox-services/multiplayer/overviews/multiplayer-intro.md)