Tópicos avançados de sessões multiplayer - XBOX Game Development Documentation

Use este tópico para conhecer conceitos avançados de sessões multiplayer. Este tópico aborda o seguinte:

Visão geral da sessão
Propriedades dos membros
Capacidades da sessão
Tamanho da sessão
Estados de usuário da sessão
Visibilidade e possibilidade de entrada
Tempos limite da sessão
Vários usuários conectados em um único console
Gerenciamento do ciclo de vida do processo
Limpeza de sessões inativas
Árbitro da sessão

Visão geral da sessão

Uma sessão no Multiplayer Session Directory (MPSD) tem um nome de sessão e é identificada como uma instância de um modelo de sessão. Um modelo de sessão é um documento JSON que fornece as configurações padrão da sessão. O modelo de sessão faz parte de uma configuração de serviço com um identificador de configuração de serviço (SCID), que é um GUID. O modelo de sessão fica no Partner Center. As configurações de serviço são os recursos voltados ao desenvolvedor usados para ingestão, gerenciamento e política de segurança. Quando uma sessão é acessada por meio do MPSD, a autorização da entidade de segurança é realizada em relação à configuração de serviço, de acordo com as políticas de acesso definidas pelo desenvolvedor no Partner Center. Verificações de acesso secundárias, como a validação da associação à sessão, são realizadas no nível da sessão quando ela é carregada, depois que o acesso à configuração de serviço é autorizado.

A funcionalidade definida por meio de um modelo não pode ser alterada por meio de gravações no MPSD. Para alterar os valores, você deve criar e enviar um novo modelo com as alterações necessárias. Todos os itens que não são definidos por meio de um modelo podem ser alterados por meio de gravações no MPSD.

Número da versão do contrato

Este tópico pressupõe que seu modelo usa a versão de contrato 107, que é a versão usada pelo MPSD atual para o XBOX One (ou posterior).

Referência da sessão

Cada sessão do MPSD é referenciada de forma exclusiva por uma referência de sessão, representada na API multiplayer pela estrutura XblMultiplayerSessionReference. A referência de sessão contém os valores de cadeia de caracteres a seguir.

Identificador de configuração de serviço (SCID)
Nome do modelo de sessão
Nome da sessão

A referência de sessão é mapeada para o URI que identifica as sessões, conforme mostrado a seguir. No mapeamento de exemplo a seguir, authority é sessiondirectory.xboxlive.com.

https://{authority}/serviceconfigs/{service-config-id}/sessiontemplates/{session-template-name}/sessions/{session-name}

Elementos de uma sessão

Cada sessão contém grupos de elementos que impõem regras de mutabilidade e de segurança. Eles variam de acordo com o elemento da sessão, junto com informações de manutenção somente leitura (metadados). Esta seção descreve os grupos de elementos de sessão incluídos nos arquivos JSON para configurar sua sessão e no arquivo JSON do modelo que você escolher.

Se você estiver usando wrappers personalizados para uma implementação HTTP/REST, sua sessão e seu modelo devem definir objetos JSON que reflitam com precisão a funcionalidade da implementação.

Há dois objetos internos dentro de cada um dos grupos de elementos.

Objetos de sistema: esses objetos têm um esquema fixo que é imposto e interpretado pelo MPSD. Eles são validados e mesclados. Como o MPSD define e sabe o que eles significam, ele pode agir com base neles. Para obter a definição completa de cada um dos objetos de sistema, consulte as referências do prefixo XblMultiplayerSession e dos URIs do Session Directory.
Objetos personalizados: esses objetos são opcionais e não têm esquema. Eles são usados para armazenar metadados relacionados a um jogo multiplayer. Como o MPSD não consegue interpretar esses dados, ele não age com base neles. Dados do jogo ou informações salvas devem ser armazenados no Title-Managed Storage (TMS). Para obter mais informações sobre o TMS, consulte a visão geral do Title Storage dos serviços do XBOX.

Veja a seguir um exemplo de objeto JSON personalizado.

    "custom": {
      "myField1": true,
      "myField2": "string",
      "myField3": 5.5,
      "myField4": { "myObject": null },
      "myField5": [ "my", "array" ]
    }

Constantes da sessão

As constantes da sessão são definidas somente no momento da criação, pelo criador ou pelo modelo de sessão. O objeto /constants/system é usado para definir constantes para o sistema multiplayer conforme ele é conhecido pelo MPSD. O wrapper associado a esse objeto é representado pela estrutura XblMultiplayerSessionConstants. O objeto /constants/system pode definir vários itens. Eles incluem um objeto capabilities, um objeto metrics, um objeto managedInitialization (versão de contrato do modelo 104 ou 105) ou memberInitialization (versão de contrato 107), um objeto peerToPeerRequirements, um objeto peerToHostRequirements e um objeto measurementsServerAddresses.

Propriedades da sessão

Use o objeto /properties/system para definir propriedades de sessão para o MPSD. O wrapper associado a esse objeto é a estrutura XblMultiplayerSessionProperties. As propriedades da sessão podem ser gravadas pelos membros da sessão a qualquer momento. Exemplos de propriedades de sessão no formato JSON são joinRestriction, initializationSucceeded e o objeto matchmaking. Para obter um exemplo de uso desse grupo de elementos, consulte Inicialização da sessão de destino e QoS.

Constantes dos membros

Defina as constantes dos membros no momento da entrada de cada membro da sessão. O objeto JSON é /members/{index}/constants/system. A classe wrapper que representa um membro da sessão é a estrutura XblMultiplayerSessionMember. Voltar ao início deste tópico.

Propriedades dos membros

As propriedades dos membros só podem ser gravadas por um membro da sessão. Elas são definidas no objeto /members/{index}/properties/system e refletem os elementos da estrutura XblMultiplayerSessionMember. Veja um exemplo.

    {
      // These flags control the member status and "activeTitle" and are mutually exclusive (it's an error to set both to true).
      // For each, false is the same as not present. The default status is "inactive"; that is, neither present.
      "ready": true,
      "active": false,

      // Base-64 blob, or not present. An empty string is the same as not present.
      "secureDeviceAddress": "ryY=",

      // During member initialization, if any members in the list fail, this member will also fail.
      // Can't be set on large sessions.
      "initializationGroup": [ 5 ],

      // List of the groups I'm in and the encounters I just had.
      // An encounter is a brief interaction with a group. When an encounter is reported, it counts as retroactively joining the group 30 seconds ago and just now leaving.
      // Group names use the session name validation rules (like case-insensitive).
      // On large sessions, groups are used to report who played with whom (rather than just session membership). Members
      // who are active in at least one group together at the same time are counted as playing together.
      // Empty lists are the same as no value specified.
      // The set of encounters is a point-in-time property, so it's immediately consumed and will never appear on a response.
      "groups": [ "team-buzz", "posse.99" ],
      "encounters": [ "CoffeeShop-757093D8-E41F-49D0-BB13-17A49B20C6B9" ],

      // Optional list of role preferences that the player has specified for role-based game modes.
      // All role names have to match across all members in the session. Role weights are
      // defined from 0-100.
      "RolePreference": { "medic": 75, "sniper": 25, "assault": 50, "support": 100 },

      // Quality of Service (QoS) measurements by lowercase device token.
      // Like all fields, "measurements" must be updated as a whole. It should be set once when measurement is complete, not incrementally.
      // Metrics can be omitted if they weren't successfully measured; that is, the peer is unreachable.
      // If a "measurements" object is set, it can't contain an entry for the member's own address.
      "measurements": {
        "e69c43a8": {
          "bandwidthDown": 19342,  // Kilobits per second.
          "bandwidthUp": 944,  // Kilobits per second.
          "custom": { }
        }

      // QoS measurements by game-server connection string. Like all fields, "serverMeasurements" must be updated as a whole, so it should be set once when measurement is complete.
      // If empty, it means that none of the measurements were completed within the "serverMeasurementTimeout".
      "serverMeasurements": {
        "server farm a": {
          "latency": 233  // Milliseconds.
        }
      },

      // Subscriptions for shoulder taps on session changes. The "profile" indicates which session changes to tap and other properties of the registration like the minimum time between taps.
      // The subscription is named with a title-generated GUID that's also sent back with the tap as a context ID.
      // Subscriptions can be added and removed individually, without affecting other subscriptions in the "subscriptions" object.
      // To remove a subscription, set its context ID to null.
      // (Like the "ready" and "active" flags, the "subscriptions" data is copied out and maintained internally, so the normal replace-all rule on system fields doesn't apply to "subscriptions".)
      // Can't be set on large sessions.
      "subscriptions": {
        "961dc162-3a8c-4982-b58b-0347ed086bc9": {
          "profile": "party",  // Or "matchmaking", "initialization", "roster", "queuehost", or "queue".
          "onBehalfOfTitleId": "3948320593",  // Optional decimal title ID of the registered channel. If not set, the title ID is taken from the token.
        },
        "709fef70-4638-4b94-905b-24cb02706eb5": null
      }
    }

Elementos de servidor

Servidores são entidades que não são usuários e que ingressaram ou foram convidadas para uma sessão. Os objetos JSON associados são /servers/{server-name}/constants/system e /servers/{server-name}/properties/system. Esses objetos só podem ser gravados por servidores.

No momento, o objeto /servers/{server-name}/constants/system não é usado.

Configuração da sessão

Você pode controlar a configuração das sessões das maneiras a seguir.

Use modelos de sessão ingeridos por meio do Partner Center.
Use chamadas às APIs de multiplayer e de matchmaking ou às APIs REST. Você ainda precisa usar um modelo, mas ele não precisa conter os valores que você deseja configurar. Observe que seu título não pode substituir as constantes já definidas no modelo.

Um documento JSON separado é fornecido para definir a própria sessão. Além disso, você deve implementar toda a funcionalidade de wrapper necessária para um título específico. O conteúdo dos documentos JSON e todo o código de wrapper devem refletir um ao outro com precisão e devem refletir a versão mais recente do contrato do modelo. O esquema de uma sessão tem versão definida pela versão da sessão (versão principal) e pela revisão do protocolo (versão secundária). As versões são combinadas no cabeçalho X-Xbl-Contract-Version como “100 * principal + secundária”. Por exemplo, um título v1.7 inclui o cabeçalho a seguir em todas as requisições REST, supondo a versão de contrato do modelo mais recente, 107: X-Xbl-Contract-Version: 107.

Recomendamos que a maioria dos títulos (que usam a XBOX Services API (XSAPI)) use a versão de contrato 105 e a versão de modelo de sessão 107.

Modelos de sessão

Cada modelo de sessão é um documento JSON, parte da configuração de serviço, que define a estrutura da sessão que está sendo criada e fornece constantes para a nova sessão. Para obter mais informações, consulte Modelos de sessão multiplayer. Voltar ao início deste tópico.

Capacidades da sessão

As capacidades são constantes na sessão do MPSD que configuram o comportamento que o MPSD deve aplicar a essa sessão. Normalmente, você usa o Partner Center para definir as capacidades no modelo de sessão. As capacidades são definidas no objeto /constants/system/capabilities. Se nenhuma capacidade for necessária, use um objeto capabilities vazio.

Os títulos quase nunca alteram ou acessam as capacidades da sessão usando a API multiplayer ou a API de matchmaking.

As capacidades da sessão são representadas pela estrutura XblMultiplayerSessionCapabilities. Elas são valores booleanos que indicam o que a sessão pode oferecer.

Conectividade
Jogabilidade
Tamanho grande
Conexão obrigatória para membros ativos

A estrutura XblMultiplayerSessionConstants contém um membro SessionCapabilities (do tipo XblMultiplayerSessionCapabilities) que define as propriedades a seguir relacionadas às capacidades da sessão.

CapabilitiesConnectivity
CapabilitiesGameplay
CapabilitiesLarge

Se o título definir uma capacidade de sessão dinâmica, a propriedade correspondente será definida como true nas constantes da sessão.

Voltar ao início deste tópico.

Tamanho da sessão

O tamanho de uma sessão do MPSD é determinado pelo número de membros dessa sessão.

Tamanho máximo da sessão

O tamanho máximo de uma sessão é o número máximo de membros que ela pode acomodar. Ele é representado pela propriedade XblMultiplayerSessionConstants::MaxMembersInSession. O tamanho máximo de membros é definido no objeto /constants/system. O tamanho máximo da sessão fica entre 1 e 100 membros e, se não for definido na criação, o padrão é 100. Se o tamanho necessário for maior que 100, a sessão é chamada de sessão “grande” e é definida de uma forma especial.

Desconexão

Definir um tamanho máximo para uma sessão pode fazer com que uma vaga aberta apareça como ocupada em determinados cenários de desconexão. Por exemplo, se um jogador for desconectado como resultado de uma falha de rede ou de energia, o atraso não é refletido imediatamente na sessão. O membro é definido como Inactive usando o recurso de detecção de desconexão. Para obter mais informações, consulte a seção Tratamento de notificações de alteração e detecção de desconexão do MPSD no tópico Visão geral do Multiplayer Session Directory. Em comparação, uma malha de pares que usa um sinal de pulsação para detectar uma desconexão geralmente fica ciente de uma desconexão em dois a três segundos e pode liberar a vaga do jogador imediatamente. No entanto, o árbitro não pode remover outros membros.

Sessões grandes

Uma sessão grande do MPSD pode ter até 1.000 membros, mas alguns recursos de sessão ficam desabilitados, como obter uma lista de todos os membros. O fato de uma sessão ser grande é representado pela propriedade XblMultiplayerSessionCapabilities::Large. Essa propriedade é definida como true para indicar uma sessão grande. A capacidade “large” é indicada no objeto /constants/system/capabilities. Para obter mais informações, consulte Capacidades da sessão. Voltar ao início deste tópico.

Estados de usuário da sessão

O MPSD define um estado de usuário como o status de um usuário que foi adicionado a uma sessão. Os estados de usuário possíveis são definidos pela enumeração XblMultiplayerSessionStatus. Também se considera que o usuário tem o status “available” antes de ser adicionado a uma sessão. Você pode usar XblMultiplayerSessionCurrentUserSetStatus para alterar o estado de usuário da sessão. Para REST, faça essa alteração definindo /members/{index}/properties/system corretamente no documento JSON da sessão de jogo.

Estado de usuário Reserved

O usuário é colocado no estado de usuário Reserved quando o árbitro o seleciona para preencher uma das vagas abertas na sessão. Nesse estado, o usuário ainda não aceitou oficialmente o convite para a sessão nem ingressou na sessão para começar a se conectar com os pares.

Estado de usuário Active

Quando um usuário está no estado Active, o título ingressou na sessão em nome do usuário, e o usuário está participando ativamente da sessão. O usuário permanece nesse estado enquanto estiver jogando. Quando um título é iniciado pela primeira vez, ele deve verificar se o usuário já é membro de alguma sessão, normalmente verificando o estado da sessão. Se o usuário for membro de uma sessão, o título pode ir direto para o jogo e definir todos os membros locais participantes com o estado de usuário Active. Um usuário deve permanecer no estado Active enquanto estiver jogando na sessão. Se um usuário sair da sessão usando a interface do usuário do jogo, ele deverá ser removido da sessão chamando XblMultiplayerSessionLeave. Se o usuário estiver apenas temporariamente ausente do jogo, como quando o título está restrito, o título deverá manter o usuário no estado Active por um período razoável. É apropriado alterar o estado do usuário para Inactive se ele não tiver retornado após um período especificado pelo título.

Estado de usuário Inactive

No estado Inactive, o usuário não está envolvido no jogo no momento, mas ainda tem uma vaga reservada na sessão. Em outras palavras, o usuário está “não ativo”. É o próprio console do usuário que é responsável por defini-lo com o estado de usuário Inactive na sessão. O árbitro não pode fazer isso. Exemplos de cenários em que um usuário é colocado no estado Inactive incluem os seguintes:

O título recebe um evento Suspending.
O usuário ficou inativo (sem entrada ou resposta do controle) por um período definido pelo título. Recomendamos dois minutos para um jogo multiplayer competitivo.
O título ficou no modo restrito por mais de dois minutos ou por um período definido pelo título. Esse período de tempo limite do modo restrito é o tempo esperado durante o qual um usuário pode ficar ausente do título usando um aplicativo relacionado ou outra experiência relacionada ao título.
O usuário foi desconectado da sessão de forma abrupta. Para obter mais informações, consulte a seção Tratamento de notificações de alteração e detecção de desconexão do MPSD no tópico Visão geral do Multiplayer Session Directory.

Se o título for iniciado e o estado de usuário de um determinado membro da sessão estiver definido como Inactive, o título foi suspenso ou o usuário ficou inativo por muito tempo na sessão. Como o título está sendo iniciado novamente, isso indica que o usuário deseja continuar com a sessão de jogo à qual pertence. Se o estado do usuário for Active quando o título for iniciado, essa situação provavelmente se deve a uma desconexão de rede ou a outro cenário em que o título não conseguiu definir o usuário como Inactive antes de ser interrompido. Em ambos os casos, seu título deve tentar reconectar o usuário ao jogo e permitir que os outros usuários continuem jogando ou remover o usuário da sessão.

Estado do usuário quando a sessão termina

Quando a sessão termina, a jogabilidade é encerrada. O título deve permitir que todos os usuários se removam usando XblMultiplayerSessionLeave. As atividades de sessão associadas aos usuários são limpas automaticamente quando eles saem da sessão. Voltar ao início deste tópico.

Visibilidade e possibilidade de entrada

O acesso à sessão é controlado no nível do MPSD por duas configurações: a visibilidade da sessão e a possibilidade de entrada na sessão. As recomendações de visibilidade e de possibilidade de entrada que fazemos neste tópico se aplicam aos cenários de títulos mais comuns. Os títulos devem seguir essas configurações, se possível. Eles devem usar a lógica do título para tomar a decisão final e definitiva sobre a admissão de um novo jogador em uma sessão.

Visibilidade da sessão

A visibilidade da sessão é representada por uma constante definida na criação da sessão. Normalmente, ela é definida no modelo de sessão e determina quais tipos de usuários têm acesso de leitura e gravação a uma sessão. Os valores possíveis para a visibilidade da sessão são definidos por XblMultiplayerSearchHandleGetVisibility. As configurações permitidas para a constante de visibilidade em um arquivo JSON são open, visible e private.

Visibilidade de sessão de jogo recomendada: open

Sessões de jogo abertas não exigem reservas de jogadores, o que simplifica o processo de convite. O árbitro não reserva jogadores no MPSD depois que um convite é enviado, mas apenas acompanha localmente os jogadores convidados. Como resultado, os jogadores podem se conectar imediatamente ao árbitro e determinar se devem ingressar em uma sessão, se foram rejeitados ou se devem aguardar (se houver suporte a jogadores em espera). O árbitro é a autoridade máxima. Ele responde e instrui o novo membro a permanecer na sessão ou sair dela. Usar a visibilidade de sessão de jogo aberta exige que o jogador convidado inicie um título e se conecte ao árbitro antes que a decisão final seja tomada. Você pode exibir uma mensagem de erro ao usuário se uma sessão estiver cheia ou se um convite tiver sido rejeitado. Para estabelecer uma conexão com o árbitro, é necessário um endereço de dispositivo seguro. A propriedade XblMultiplayerSessionProperties::HostDeviceToken é usada para descobrir qual membro da sessão é o árbitro atual de uma sessão e qual endereço de dispositivo seguro um jogador convidado deve usar para a conexão.

Possibilidade de entrada na sessão

A possibilidade de entrada na sessão determina quais tipos de usuários podem ingressar em uma sessão. Ela pode ser definida dinamicamente durante uma sessão. Os valores possíveis para a possibilidade de entrada na sessão são os seguintes.

None (padrão): não há restrições sobre quem pode ingressar na sessão.
Local: somente usuários locais podem ingressar na sessão.
Followed: somente usuários locais e usuários seguidos por outros membros da sessão podem ingressar na sessão sem reserva.

Um árbitro de sessão pode criar uma sessão privada por meio da configuração de possibilidade de entrada. Definir a possibilidade de entrada como local ou followed restringe o acesso à sessão e a torna privada. O árbitro também deve acompanhar a possibilidade de entrada na sessão, para que convites de sessão mais antigos possam ser rejeitados no nível do host, se necessário. Por exemplo, se algum jogador convidado não tiver chegado para ingressar em uma sessão até que ela já esteja cheia, o árbitro pode informar aos jogadores que estão ingressando que a sessão foi bloqueada e que eles precisam sair da sessão automaticamente. Voltar ao início deste tópico.

Tempos limite da sessão

As sessões podem ser alteradas por temporizadores e outros eventos externos. Os tempos limite da sessão definem os períodos durante os quais os membros da sessão podem permanecer em estados específicos antes de serem automaticamente tornados inativos ou removidos da sessão. O MPSD também oferece suporte a tempos limite para gerenciar a vida útil da sessão.

As configurações de tempo limite são feitas em /constants/system/timeouts, ou no objeto de inicialização gerenciada, para a versão de contrato do modelo 104 ou 105. Para a versão 107 ou posterior, as configurações são feitas individualmente em /constants/system ou no objeto de inicialização gerenciada.

Quando um temporizador expira, o MPSD não atualiza automaticamente a sessão nem notifica o árbitro sobre alterações naquele instante. Os estados da sessão e de tempo limite só são atualizados imediatamente antes do envio de uma requisição de leitura ou gravação. A atualização imediata garante que os dados retornados sejam os mais atualizados.

Os tempos limite da sessão não são empilhados. Apenas um é aplicado a uma transição de estado de cada membro da sessão em uma atualização.

Tempos limite definidos atualmente

Esta seção descreve os tempos limite definidos atualmente pelo MPSD.

Todos os tempos limite são especificados em milissegundos.
Um valor 0 é permitido e indica um tempo limite imediato.
Um tempo limite sem valor é considerado infinito.

Como os tempos limite têm valores padrão, você deve especificar null explicitamente para um tempo limite infinito.

evaluationTimeout

Esse tempo limite indica o tempo que um membro da sessão tem para tomar e carregar a decisão de avaliação. Se nenhuma decisão for recebida, a decisão contará como falha. Esse tempo limite é colocado no objeto de inicialização gerenciada.

inactiveRemovalTimeout

Esse tempo limite é definido para um membro da sessão que ingressou em uma sessão, mas não está envolvido no jogo no momento. Por padrão, o membro é removido da sessão após duas horas.

Esse tempo limite é designado como tempo limite de inatividade para a versão de contrato do modelo 104 ou 105.

Em muitos casos, recomendamos definir o tempo limite de inatividade como 0. Isso faz com que qualquer usuário definido com o estado Inactive seja removido imediatamente da sessão e a vaga correspondente seja liberada. Esse comportamento é desejável na maioria dos jogos multiplayer competitivos para que, se um usuário ficar inativo ou atingir o estado Inactive, um novo jogador possa ser adicionado rapidamente. Para jogos cooperativos ou outros designs multiplayer, talvez você queira que seu título dê aos usuários mais tempo para se reconectar se forem desconectados ou não estiverem envolvidos no título por certos períodos. Observe que nenhuma solução única se aplica a todos os cenários de design.

joinTimeout

Esse tempo limite indica o número de milissegundos que um usuário tem para ingressar na sessão. As reservas são removidas para os usuários que não conseguem ingressar na sessão. Esse tempo limite é colocado no objeto de inicialização gerenciada.

measurementTimeout

Esse tempo limite indica o tempo que um membro da sessão tem para carregar as medições. Um membro que não carrega as medições é marcado com o motivo de falha “timeout”. Esse tempo limite é colocado no objeto de inicialização gerenciada.

Durante o matchmaking, é imposto um tempo limite de 45 segundos para as medições de QoS. Como resultado, recomendamos usar um tempo limite de medição menor ou igual a 30 segundos durante o matchmaking.

readyRemovalTimeout

Esse tempo limite é definido para um membro da sessão que ingressou na sessão e está tentando entrar no jogo. Isso geralmente significa que o shell adicionou o usuário à sessão em nome do título e que o título está sendo iniciado. Por padrão, o membro é removido da sessão e colocado no estado Inactive após três minutos.

Esse tempo limite é designado como tempo limite de pronto para a versão de contrato 104 ou 105.

reservedRemovalTimeout

Esse tempo limite é definido para um membro da sessão que foi adicionado à sessão por outra pessoa, mas ainda não ingressou nela. A reserva é excluída e o membro é considerado inativo quando o tempo limite expira. O valor padrão é 30 segundos.

Esse tempo limite é designado como tempo limite de reserva para a versão de contrato 104 ou 105.

sessionEmptyTimeout

Esse tempo limite indica o número de milissegundos após uma sessão ficar vazia até que ela seja excluída. O valor padrão é 0.

Esse tempo limite é designado como tempo limite sessionEmpty para a versão de contrato 104 ou 105.

Exemplo de tempo limite de sessão

Uma sessão é iniciada com quatro jogadores.
Dois jogadores, A e B, são desconectados devido a uma falha de energia. O status deles no jogo permanece Active.
Os outros dois jogadores, C e D, saem corretamente usando XblMultiplayerSessionLeave.
A sessão permanece aberta. Os jogadores A e B estão desconectados, mas ainda estão no estado Active.
Alguns dias depois, o jogador A volta e inicia o jogo.
O jogo do jogador A verifica as sessões das quais o jogador A é membro (executa uma leitura) e encontra a sessão órfã de alguns dias atrás.
A sessão faz uma verificação de presença nos dois jogadores que ainda estão na sessão (A e B).
1. Como o jogador A está executando o título, a verificação de presença do jogador A é bem-sucedida. O estado Active do jogador na partida permanece o mesmo.
2. O jogador B não está executando o título. Como resultado, a verificação de presença do jogador B falha. O serviço define o estado do jogador B como Inactive. Nesse momento, o tempo limite de inatividade do jogador B começa.
O jogador A sai da sessão corretamente usando o método XblMultiplayerSessionLeave.
O tempo limite de inatividade expira para o jogador B, que é removido da sessão na próxima leitura ou gravação feita por qualquer pessoa.
Agora a sessão tem zero membros e é removida do serviço.

Se o tempo limite de inatividade da sessão de exemplo for definido como 0, o jogador B atingirá o tempo limite imediatamente após a verificação de presença na etapa 7.1 e provavelmente será removido pela gravação da sessão. Nesse caso, a sessão é encerrada sem a necessidade de uma leitura ou gravação adicional na sessão. Voltar ao início deste tópico.

Vários usuários conectados em um único console

Quando vários usuários estão conectados no mesmo console, é possível que alguns usuários estejam em uma sessão de jogo enquanto outros não estão na sessão ou não estão ativos no título atual. Convites de jogo também podem ser recebidos e aceitos por vários usuários, afetando a associação à sessão de jogo. Considere essas informações para que seu título possa tratar corretamente todos os cenários de associação à sessão. Em um cenário comum, um novo jogador entra, fica ativo no jogo e precisa ser adicionado a uma sessão de jogo existente. Assim como ao criar uma nova sessão de jogo, um título só deve adicionar um usuário quando for apropriado durante a jogabilidade. Com vários usuários conectados, um ou mais usuários também podem receber convites para outra sessão de jogo. Os títulos não precisam tratar esses cenários de nenhuma forma específica. Os eventos de estado da sessão e de membros notificam o título sobre quaisquer atualizações na sessão de jogo e na associação dos usuários. Para tratar vários usuários conectados em uma sessão online, o título assina shoulder taps para todos os usuários, usando um objeto XboxLiveContext Class separado para cada usuário. O título usa a propriedade XblMultiplayerSessionInfo::ChangeNumber para determinar alterações específicas na sessão e ignorar shoulder taps duplicados. Voltar ao início deste tópico.

Gerenciamento do ciclo de vida do processo

Assim como um título que não é multiplayer, um título em uma sessão multiplayer pode passar por eventos de suspensão e de encerramento do ciclo de vida do processo. Como resultado, o árbitro da sessão deve salvar periodicamente o estado da sessão. Caso o árbitro seja suspenso, o título deve tentar a migração do árbitro e salvar o estado do jogo conforme apropriado. Um novo árbitro pode então restaurar o estado da sessão. Assim, é possível que uma sessão multiplayer completa seja suspensa e retomada mais tarde, se a sessão ainda for válida no MPSD. Somente um par designado, normalmente o host do jogo, deve atualizar o estado global do jogo.

Armazenamento de metadados do jogo

Um título armazena os metadados do jogo na sessão do MPSD. Os metadados do jogo são as informações necessárias para exibir os dados da sessão e permitir que o título encontre a sessão de jogo e ingresse nela. O título armazena os metadados específicos do jogador na seção de propriedades personalizadas do membro da sessão. Por exemplo, a cor do jogador e a arma preferida do jogador na sessão. Os metadados de toda a sessão, como o mapa atual, são armazenados na seção de propriedades personalizadas globais da sessão do MPSD.

Armazenamento do estado do jogo

O estado do jogo é armazenado no TMS usando o serviço Title Storage. O armazenamento nesse local permite que um título migre o árbitro sem preocupações com permissões. Para obter mais informações, consulte Migrando um árbitro.

O título não deve tentar salvar o estado do jogo no TMS com frequência maior que uma vez a cada cinco minutos, a menos que esteja sendo suspenso.

Voltar ao início deste tópico.

Limpeza de sessões inativas

Se sessionEmptyTimeout for definido como 0, uma sessão do MPSD será excluída automaticamente quando o último jogador sair da sessão. Para saber como impedir que uma sessão não utilizada contenha jogadores após uma falha ou desconexão, consulte a seção Tratamento de notificações de alteração e detecção de desconexão do MPSD no tópico Visão geral do Multiplayer Session Directory. O tratamento inadequado de sessões não utilizadas após uma falha ou desconexão pode causar problemas quando um título consulta as sessões de um jogador. Recomendamos limpar as sessões inativas fazendo com que o título consulte todas as sessões de um usuário específico chamando XblMultiplayerGetSessionAsync e, em seguida, avaliando as sessões. Quando o título encontra uma sessão obsoleta, ele chama XblMultiplayerSessionLeave para todos os jogadores locais na sessão. Essa chamada acaba reduzindo a contagem de membros para 0 e limpa as sessões. Voltar ao início deste tópico.

Árbitro da sessão

Alguns métodos multiplayer só devem ser chamados por um cliente dentro de uma sessão de jogo. Esse cliente é um dos consoles que participam da sessão, chamado de árbitro, ou host. Se pelo menos um membro da sessão estiver em um jogo, a sessão deverá ter um árbitro para monitorar as entradas em andamento.

Definindo o árbitro

Quando uma sessão é criada pelo cliente, ele designa um console como árbitro. Para obter mais informações, consulte a seção Definir um árbitro para uma sessão do MPSD no tópico Tarefas de multiplayer.

Salvando o estado da sessão

Conforme descrito na seção Gerenciamento do ciclo de vida do processo, o árbitro deve salvar periodicamente o estado da sessão. Um novo árbitro deve ser capaz de restaurar o estado da sessão em caso de migração do árbitro pelo título. Para obter mais informações, consulte Migrando um árbitro.

Gerenciando os membros da sessão de jogo e as entradas em andamento

A função mais importante do árbitro da sessão é gerenciar os usuários que entram na sessão de jogo para jogar. Isso inclui tratar convites de jogo, notificar jogadores em espera e lidar com jogadores que saem do jogo.

Recebendo notificações

O árbitro deve escutar novos jogadores que desejam ingressar na sessão de jogo usando XblMultiplayerSessionChangedHandler.

Encontrando jogadores para preencher vagas vazias na sessão de jogo

O árbitro encontra jogadores para preencher vagas vazias na sessão de jogo usando uma das operações a seguir.

Se o seu título usa uma sessão de lobby ou outro mecanismo para permitir entradas posteriores, encontre novos membros da sessão usando esse mecanismo.
Crie outra sessão de tíquete de partida.

Para obter mais informações, consulte a seção Preencher vagas abertas da sessão durante o matchmaking no tópico Tarefas de multiplayer.

Tratando os membros convidados da sessão

O árbitro deve monitorar os membros convidados da sessão e aplicar um intervalo mínimo entre os convites a um mesmo usuário. Para obter mais informações, consulte a seção Enviar convites de jogo no tópico Tarefas de multiplayer.

Última modificação em 8 de outubro de 2026

⌘I

​Visão geral da sessão

​Número da versão do contrato

​Referência da sessão

​Elementos de uma sessão

​Constantes da sessão

​Propriedades da sessão

​Constantes dos membros

​Propriedades dos membros

​Elementos de servidor

​Configuração da sessão

​Modelos de sessão

​Capacidades da sessão

​Tamanho da sessão

​Tamanho máximo da sessão

​Desconexão

​Sessões grandes

​Estados de usuário da sessão

​Estado de usuário Reserved

​Estado de usuário Active

​Estado de usuário Inactive

​Estado do usuário quando a sessão termina

​Visibilidade e possibilidade de entrada

​Visibilidade da sessão

​Visibilidade de sessão de jogo recomendada: open

​Possibilidade de entrada na sessão

​Tempos limite da sessão

​Tempos limite definidos atualmente

​evaluationTimeout

​inactiveRemovalTimeout

​joinTimeout

​measurementTimeout

​readyRemovalTimeout

​reservedRemovalTimeout

​sessionEmptyTimeout

​Exemplo de tempo limite de sessão

​Vários usuários conectados em um único console

​Gerenciamento do ciclo de vida do processo

​Armazenamento de metadados do jogo

​Armazenamento do estado do jogo

​Limpeza de sessões inativas

​Árbitro da sessão

​Definindo o árbitro

​Salvando o estado da sessão

​Gerenciando os membros da sessão de jogo e as entradas em andamento

​Recebendo notificações

​Encontrando jogadores para preencher vagas vazias na sessão de jogo

​Tratando os membros convidados da sessão

Visão geral da sessão

Número da versão do contrato

Referência da sessão

Elementos de uma sessão

Constantes da sessão

Propriedades da sessão

Constantes dos membros

Propriedades dos membros

Elementos de servidor

Configuração da sessão

Modelos de sessão

Capacidades da sessão

Tamanho da sessão

Tamanho máximo da sessão

Desconexão

Sessões grandes

Estados de usuário da sessão

Estado de usuário Reserved

Estado de usuário Active

Estado de usuário Inactive

Estado do usuário quando a sessão termina

Visibilidade e possibilidade de entrada

Visibilidade da sessão

Visibilidade de sessão de jogo recomendada: open

Possibilidade de entrada na sessão

Tempos limite da sessão

Tempos limite definidos atualmente

evaluationTimeout

inactiveRemovalTimeout

joinTimeout

measurementTimeout

readyRemovalTimeout

reservedRemovalTimeout

sessionEmptyTimeout

Exemplo de tempo limite de sessão

Vários usuários conectados em um único console

Gerenciamento do ciclo de vida do processo

Armazenamento de metadados do jogo

Armazenamento do estado do jogo

Limpeza de sessões inativas

Árbitro da sessão

Definindo o árbitro

Salvando o estado da sessão

Gerenciando os membros da sessão de jogo e as entradas em andamento

Recebendo notificações

Encontrando jogadores para preencher vagas vazias na sessão de jogo

Tratando os membros convidados da sessão