Tarefas de multijogador

• Assinar notificações de alteração de sessão do Multiplayer Session Directory (MPSD)
• Criar uma sessão do MPSD
• Definir um árbitro para uma sessão do MPSD
• Gerenciar a ativação do título
• Tornar o usuário disponível para entrada
• Enviar convites de jogo
• Entrar em uma sessão de jogo a partir de uma sessão de lobby
• Entrar em uma sessão do MPSD a partir de uma ativação do título
• Definir a atividade atual do usuário
• Atualizar uma sessão do MPSD
• Sair de uma sessão do MPSD
• Preencher vagas abertas na sessão durante o matchmaking
• Criar um tíquete de partida
• Obter o status do tíquete de partida

​

Assinar notificações de alteração de sessão do Multiplayer Session Directory (MPSD)

1. Use o mesmo objeto XblContextHandle para todas as chamadas do mesmo usuário. As assinaturas estão vinculadas ao tempo de vida desse objeto. Se houver vários usuários locais, use um objeto XblContextHandle separado para cada usuário.
2. Implemente manipuladores de eventos para XblMultiplayerAddSessionChangedHandler e XblMultiplayerSessionSubscriptionLostHandler.
3. Se estiver assinando alterações para mais de um usuário, adicione código ao manipulador de eventos XblMultiplayerAddSessionChangedHandler para evitar trabalho desnecessário. Use a propriedade XblMultiplayerSessionChangeEventArgs::Branch e a propriedade XblMultiplayerSessionChangeEventArgs::ChangeNumber. Usar essas propriedades permite acompanhar a última alteração vista e ignorar alterações mais antigas.
4. Chame XblMultiplayerSetSubscriptionsEnabled para permitir as assinaturas.
5. Crie um objeto de sessão local e, em seguida, entre nessa sessão como ativo.
6. Faça chamadas para cada usuário a XblMultiplayerAddSessionChangedHandler, passando o tipo de alteração de sessão sobre o qual deseja ser notificado.
7. Grave a sessão no MPSD conforme descrito na seção Atualizar uma sessão do MPSD deste tópico.

​

Analisando notificações de alteração de sessão duplicadas

• Armazenar o valor mais recente da propriedade ChangeNumber para cada valor da propriedade Branch avaliado.
• Se um shoulder tap tiver um valor da propriedade ChangeNumber maior que o último valor armazenado para aquele valor da propriedade Branch, processar o shoulder tap e, em seguida, atualizar o valor mais recente da propriedade ChangeNumber.
• Se um shoulder tap não tiver um valor da propriedade ChangeNumber maior para aquele valor da propriedade Branch, ignorar o processamento do shoulder tap. Essa alteração de sessão já foi tratada.

​

Criar uma sessão do MPSD

1. Crie um novo objeto XblContextHandle. Seu título cria esse objeto uma vez, armazena-o e o reutiliza conforme necessário em todo o código-fonte. É necessário usar exatamente o mesmo contexto, especialmente ao trabalhar com assinaturas de sessão.
2. Crie um novo XblMultiplayerSessionHandle com XblMultiplayerSessionCreateHandle para preparar todos os dados de sessão de que o MPSD precisa para criar uma nova sessão.
3. Faça as alterações necessárias antes de gravar a sessão no MPSD. Por exemplo, ao fazer um membro entrar na sessão com uma chamada a XblMultiplayerSessionJoin, o cliente adiciona dados de solicitação locais ocultos que instruem o MPSD a realizar a entrada na chamada para atualizar a sessão.
4. Quando terminar de fazer as alterações locais, grave-as no MPSD conforme descrito na seção Atualizar uma sessão do MPSD deste tópico.
5. Receba do MPSD o novo objeto XblMultiplayerSessionHandle, com muitos campos preenchidos.
6. Use o novo objeto de sessão daqui em diante. Descarte a cópia antiga, que contém uma solicitação oculta para criar uma nova sessão.

​

Exemplo

auto asyncBlock = std::make_unique<XAsyncBlock>();
asyncBlock->queue = queue;
asyncBlock->context = nullptr;
asyncBlock->callback = [](XAsyncBlock* asyncBlock)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock }; // Take over ownership of the XAsyncBlock*.

    XblMultiplayerSessionHandle sessionHandle;
    HRESULT hr = XblMultiplayerWriteSessionResult(asyncBlock, &sessionHandle);
    if (SUCCEEDED(hr))
    {
        // Process multiplayer session handle.
    }
    else
    {
        // Handle failure.
    }
};

XblMultiplayerSessionReference ref;
pal::strcpy(ref.Scid, sizeof(ref.Scid), SCID);
pal::strcpy(ref.SessionTemplateName, sizeof(ref.SessionTemplateName), SESSION_TEMPLATE_NAME);
pal::strcpy(ref.SessionName, sizeof(ref.SessionName), SESSION_NAME);

XblMultiplayerSessionInitArgs args = {};

XblMultiplayerSessionHandle sessionHandle = XblMultiplayerSessionCreateHandle(XUID, &ref, &args);

auto hr = XblMultiplayerSessionJoin(
    sessionHandle,
    memberCustomConstantsJson.c_str(),
    initializeRequested,
    joinWithActiveStatus);
    
 hr = XblMultiplayerWriteSessionAsync(xblContextHandle, sessionHandle, XblMultiplayerSessionWriteMode::CreateNew, asyncBlock.get());
if (SUCCEEDED(hr))
{
    // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* because the callback will take over ownership.
    // If the call fails, std::unique_ptr will keep ownership and delete XAsyncBlock*.
    asyncBlock.release();
}

• XAsyncBlock
• XblMultiplayerSessionCreateHandle
• XblMultiplayerSessionInitArgs
• XblMultiplayerSessionReference
• XblMultiplayerSessionWriteMode
• XblMultiplayerWriteSessionAsync
• XblMultiplayerWriteSessionResult

​

Definir um árbitro para uma sessão do MPSD

1. Recupere do MPSD os tokens de dispositivo dos candidatos a host chamando XblMultiplayerSessionMembers.

   [!NOTE] Se a sessão tiver sido criada pelo matchmaking do SmartMatch, seus clientes poderão usar os candidatos a host disponíveis no MPSD chamando XblMultiplayerSessionHostCandidates.

2. Selecione o host desejado na lista de candidatos a host.
3. Chame XblMultiplayerSessionSetHostDeviceToken para definir o token de dispositivo no cache local do MPSD. Se a chamada para definir o token de dispositivo do host for bem-sucedida, o token de dispositivo local substituirá o token do host.
4. Se um código de status HTTP/412 for recebido ao tentar definir o token de dispositivo do host, consulte os dados da sessão. Veja se o token de dispositivo do host é do console local. Se não for do console local, outro console foi designado como árbitro.

   [!NOTE] Seu cliente deve tratar o código de status HTTP/412 separadamente dos outros códigos HTTP, porque HTTP/412 não indica uma falha padrão. Para obter mais informações sobre esse código de status, veja Códigos de status de sessões multijogador.

5. Atualize a sessão no MPSD conforme descrito na seção Atualizar uma sessão do MPSD deste tópico.

   [!NOTE] Se você não tiver um algoritmo melhor, o cliente poderá implementar um algoritmo guloso no qual cada candidato a host tenta se definir como host se ninguém mais tiver feito isso ainda. Para obter mais informações, veja a seção Árbitro da sessão no tópico Tópicos avançados de sessões multijogador.

​

Gerenciar a ativação do título

1. Configure um manipulador de eventos para o evento CoreApplicationView.Activated. Esse manipulador é disparado sempre que ocorre uma ativação de protocolo, mesmo que o título já esteja em execução.
2. Na ativação do título, inicie uma sessão e assine as notificações de alteração da sessão. Para obter mais informações, veja Assinar notificações de alteração de sessão do MPSD neste tópico.
3. Faça o usuário entrar na sessão como ativo. Para obter mais informações, veja Entrar em uma sessão do MPSD a partir de uma ativação do título neste tópico.
4. Defina a sessão de lobby como a sessão de atividade exposta por meio da interface do usuário do perfil. Para obter mais informações, veja Definir a atividade atual do usuário neste tópico.
5. Faça o usuário entrar na sessão de jogo como ativo. O usuário agora pode se conectar aos pares e entrar no jogo ou no lobby.

​

Tornar o usuário disponível para entrada

1. Criar um objeto de sessão e, em seguida, modificar os atributos conforme necessário.
2. Fazer o usuário entrar na sessão como ativo. Para obter mais informações, veja Entrar em uma sessão do MPSD a partir de uma ativação do título neste tópico.
3. Determinar se o usuário foi designado como árbitro da sessão.
4. Se o usuário não for o árbitro, ir para a etapa 7.
5. Se o usuário for o árbitro, chamar XblMultiplayerSessionSetHostDeviceToken.
6. Tentar gravar a sessão usando uma chamada a XblMultiplayerWriteSessionAsync.
7. Definir a sessão como a sessão ativa. Para obter mais informações, veja Definir a atividade atual do usuário neste tópico.

​

Enviar convites de jogo

• Enviar os convites para a sessão de lobby.
• Enviar os convites usando a interface do usuário genérica de convite da plataforma XBOX com a referência da sessão de jogo.

1. Tornar o jogo de quem convida disponível para entrada de jogadores. Para obter mais informações, veja Tornar o usuário disponível para entrada neste tópico.
2. Determinar se os convites serão enviados pela sessão de lobby ou usando a interface do usuário de convite.
3. Se a sessão de lobby estiver sendo usada, enviar os convites usando uma chamada a XblMultiplayerSendInvitesAsync. Esse método pode exigir a criação de uma lista de jogadores na interface do usuário do jogo chamando XGameUiShowPlayerPickerAsync.
4. Se a interface do usuário de convite estiver sendo usada, chamar XGameUiShowSendGameInviteAsync para mostrar a interface do usuário de convite.
5. Tratar o XblMultiplayerAddSessionChangedHandler para o jogador local depois que o jogador remoto entrar.
6. Para o jogador remoto, implementar um código de ativação do título. Para obter mais informações, veja Gerenciar a ativação do título neste tópico.

​

Entrar em uma sessão de jogo a partir de uma sessão de lobby

1. Ao criar a sessão de jogo, use a API XblMultiplayerSetTransferHandleAsync para criar um identificador de transferência que vincule a sessão de lobby e a sessão de jogo.
2. Armazene o GUID do identificador de transferência na sessão de lobby, em vez da referência de sessão da sessão de jogo.
3. Quando o título quiser mover os membros da sessão de lobby para a sessão de jogo, cada cliente usará o identificador de transferência da sessão de lobby para entrar na sessão de jogo usando a API XblMultiplayerWriteSessionByHandleAsync.
4. O MPSD consulta a sessão de lobby para verificar se os membros que estão tentando entrar na sessão de jogo usando o identificador de transferência também estão na sessão de lobby.
5. Se os membros estiverem na sessão de lobby, eles poderão acessar a sessão de jogo.

​

Entrar em uma sessão do MPSD a partir de uma ativação do título

1. Implemente um manipulador de eventos para o evento CoreApplicationView.Activated. Ele notifica as ativações do título.
2. Quando o manipulador for disparado, examine a propriedade IActivatedEventArgs.Kind. Se ela estiver definida como Protocol, converta os argumentos do evento para a classe ProtocolActivatedEventArgs.
3. Examine o objeto ProtocolActivatedEventArgs. Se o URI indicado na propriedade ProtocolActivatedEventArgs.Uri corresponder a inviteHandleAccept (correspondente a um convite aceito) ou a activityHandleJoin (correspondente a uma entrada pela interface do usuário do shell), analise a cadeia de consulta do URI. Ela é formatada como uma cadeia de consulta de URI normal com pares de chave/valor; extraia os campos a seguir.
   • Para um convite aceito:
     1. handle
     2. invitedXuid
     3. senderXuid
   • Para uma entrada:
     1. handle
     2. joinerXuid
     3. joineeXuid
4. Inicie o código multijogador do título, que deve incluir uma chamada a XblMultiplayerSetSubscriptionsEnabled.
5. Crie um objeto XblMultiplayerSessionHandle local chamando XblMultiplayerSessionCreateHandle.
6. Chame XblMultiplayerSessionJoin para entrar na sessão. Use as configurações de parâmetro a seguir para que a entrada seja definida como ativa.
   • memberCustomConstantsJson = null
   • initializeRequested = false
   • joinWithActiveStatus = true
7. Chame XblMultiplayerSessionSetSessionChangeSubscription para receber shoulder taps quando a sessão for alterada após a entrada.
8. Chame XblMultiplayerWriteSessionByHandleAsync usando o identificador obtido conforme descrito na etapa 3. O usuário agora é membro da sessão e pode usar os dados da sessão para se conectar ao jogo.

​

Definir a atividade atual do usuário

​

Atualizar uma sessão do MPSD

1. Fazer as alterações necessárias na sessão atual, por exemplo, chamando XblMultiplayerSessionLeave.
2. Quando todas as alterações forem feitas, gravar as alterações locais no MPSD usando qualquer um destes métodos.
   • XblMultiplayerWriteSessionAsync
   • XblMultiplayerWriteSessionByHandleAsync
   Defina o modo de gravação como XblMultiplayerSessionWriteMode::SynchronizedUpdate se estiver gravando em uma parte compartilhada que outros títulos também podem modificar. Para obter mais informações, veja a seção Sincronização de atualizações de sessão no tópico Visão geral do Multiplayer Session Directory. O método de gravação grava a entrada no servidor e obtém a sessão mais recente, a partir da qual é possível descobrir os outros membros da sessão e os endereços seguros de dispositivo (SDAs) dos consoles deles. Para obter mais informações sobre como estabelecer uma conexão de rede entre esses consoles, veja Introdução ao Winsock no XBOX One.
3. Descartar o objeto de sessão local antigo. Usar o objeto de sessão recém-recuperado para que as ações futuras se baseiem no estado de sessão conhecido mais recente.

​

Sair de uma sessão do MPSD

1. Chamar XblMultiplayerSessionLeave para a sessão de jogo.
2. Atualizar a sessão de jogo no MPSD conforme descrito na seção Atualizar uma sessão do MPSD deste tópico.
3. Se necessário, chamar o método XblMultiplayerSessionLeave para a sessão de lobby e, em seguida, atualizar essa sessão.
4. Se necessário para a sessão de lobby, encerrar a API multijogador cancelando o registro com chamadas a XblMultiplayerRemoveSubscriptionLostHandler e XblMultiplayerRemoveSessionChangedHandler.

​

Preencher vagas abertas na sessão durante o matchmaking

1. Acessar o estado de sessão mais recente da sessão de tíquete criada durante o matchmaking.
2. Adicionar os jogadores disponíveis para o jogo a partir da sessão de lobby.
3. Determinar se a sessão de tíquete está cheia.
4. Se a sessão estiver cheia, continuar o jogo.
5. Se a sessão ainda não estiver cheia, criar o tíquete de partida conforme descrito em Criar um tíquete de partida neste tópico. Certifique-se de criar o tíquete com o parâmetro preserveSession definido como Always.
6. Continuar com o matchmaking. Para obter mais informações, veja Visão geral do matchmaking.

​

Criar um tíquete de partida

1. Chamar XblMatchmakingCreateMatchTicketAsync, passando uma referência à sessão de tíquete. O método lê a sessão de tíquete do MPSD e inicia o matchmaking para os usuários da sessão. Internamente, o método chama POST (/serviceconfigs/{scid}/hoppers/{hoppername}).
2. Definir o parâmetro preserveSession como Never se o serviço de matchmaking for combinar os membros da sessão em uma nova sessão ou em outra sessão existente. Definir o parâmetro preserveSession como Always para permitir que o título reutilize uma sessão de jogo existente como sessão de tíquete para continuar o jogo. O serviço de matchmaking poderá então garantir que a sessão enviada seja preservada e que todos os jogadores combinados sejam adicionados a essa sessão.
3. Usar o XblCreateMatchTicketResponse::EstimatedWaitTime retornado no objeto CreateMatchTicketResponse para definir as expectativas dos usuários quanto ao tempo de matchmaking.
4. Usar o XblCreateMatchTicketResponse::MatchTicketId retornado no objeto de resposta para cancelar o matchmaking da sessão, se necessário, excluindo o tíquete. A exclusão do tíquete usa XblMatchmakingDeleteMatchTicketAsync.

​

Obter o status do tíquete de partida

1. Obter o objeto XblMultiplayerSessionHandle da sessão de tíquete.
2. Chamar XblMultiplayerSessionMatchmakingServer para acessar o objeto XblMultiplayerMatchmakingServer usado no matchmaking.
3. Verificar o objeto XblMultiplayerMatchmakingServer para determinar o status do processo de matchmaking, o tempo de espera típico da sessão e a referência da sessão de destino, caso uma partida tenha sido encontrada.