Pular para o conteúdo principal
Use este tópico para habilitar seu título a permitir que os usuários consultem uma lista de sessões de jogo multiplayer abertas que atendam aos critérios especificados, usando a navegação de sessões multiplayer. A navegação de sessões multiplayer foi introduzida em novembro de 2016. Em um cenário de navegação de sessões, um usuário em um jogo pode recuperar uma lista de sessões de jogo nas quais é possível ingressar. Cada entrada de sessão dessa lista contém alguns metadados adicionais sobre o jogo, que o usuário pode usar para ajudar a escolher em qual sessão ingressar. O usuário também pode filtrar a lista de sessões usando os metadados. Depois que o usuário encontra uma sessão de jogo que o interessa, ele pode ingressar nela. Um usuário também pode criar uma nova sessão de jogo e usar o recurso de navegação de sessões para recrutar usuários adicionais em vez de depender do matchmaking. A navegação de sessões multiplayer e o matchmaking tradicional são diferentes. Com a navegação de sessões multiplayer, o usuário seleciona em qual sessão de jogo deseja ingressar. Com o matchmaking, o usuário seleciona uma opção “encontrar um jogo” que tenta colocá-lo automaticamente em uma sessão de jogo apropriada. Embora a navegação de sessões multiplayer seja um processo manual e mais lento que nem sempre seleciona a melhor experiência de jogo para o usuário, ele tem mais controle, e o recurso de navegação pode ser percebido como a escolha de jogo subjetivamente melhor. É comum incluir cenários de navegação de sessões multiplayer e de matchmaking nos jogos. Normalmente, o matchmaking é usado para modos de jogo jogados com frequência, enquanto a navegação de sessões multiplayer é usada para jogos personalizados.

Cenário de exemplo

John quer jogar um jogo multiplayer de arena de batalha, mas quer jogar uma partida em que todos os usuários selecionem seu herói aleatoriamente. Usando a navegação de sessões multiplayer, ele pode recuperar uma lista de sessões de jogo abertas e encontrar as que incluem “random heroes” na descrição. Se a interface do usuário do título tiver a opção, ele poderá selecionar o modo de jogo “random hero” e recuperar apenas as sessões marcadas para indicar que são jogos “RandomHero”. Quando John encontrar uma sessão de jogo de que goste, ele poderá ingressar nela. Depois que pessoas suficientes ingressarem, o host da sessão de jogo poderá iniciá-la.

Funções

Uma sessão que está no recurso de navegação de sessões multiplayer pode especificar que está recrutando usuários para funções específicas. Por exemplo, um usuário pode querer criar uma sessão de jogo que especifique que ela contém no máximo cinco classes de assalto, mas deve conter pelo menos duas funções de curandeiro e pelo menos uma função de tanque. Quando outro usuário se candidata à sessão, ele pode pré-selecionar sua função. Em seguida, o serviço decide se ele pode ingressar na sessão com base em quantas vagas abertas estão disponíveis para a função selecionada. Se um usuário quiser reservar duas vagas para que seus amigos ingressem, ele pode designar uma função “amigos” para a sessão, e somente usuários que são amigos do host poderão preencher as duas vagas dedicadas à função “amigos”. Para obter mais informações sobre funções, consulte Funções no multiplayer.

Como funciona a navegação de sessões multiplayer

A navegação de sessões funciona usando identificadores de pesquisa. Um identificador de pesquisa é um pacote de dados que contém uma referência à sessão, além de metadados adicionais sobre a sessão, como atributos de pesquisa. Quando um título cria uma nova sessão de jogo qualificada para a navegação de sessões multiplayer, ele cria um identificador de pesquisa para a sessão. O identificador de pesquisa é armazenado no Multiplayer Service Directory (MPSD), que mantém os identificadores de pesquisa do título. Quando um título precisa recuperar uma lista de sessões, ele pode enviar uma consulta de pesquisa ao MPSD, que retorna uma lista de identificadores de pesquisa que atendem aos critérios de pesquisa. Em seguida, o título pode usar a lista de sessões para exibir ao usuário uma lista de jogos nos quais é possível ingressar. Quando uma sessão está cheia ou não é possível ingressar nela por outro motivo, seu título pode remover o identificador de pesquisa do MPSD para que a sessão não apareça nas consultas da navegação de sessões multiplayer.
Os identificadores de pesquisa são usados ao exibir uma lista de sessões para um usuário.
Não use identificadores de pesquisa para matchmaking em segundo plano. Para matchmaking em segundo plano, recomendamos usar o SmartMatch. Para obter mais informações, consulte Encontrando um jogo multiplayer usando o SmartMatch com o Multiplayer Manager.

Configurar uma sessão para a navegação de sessões multiplayer

Para usar identificadores de pesquisa em uma sessão, a sessão deve ter searchable e userAuthorizationStyle definidos como true. A capacidade userAuthorizationStyle só é obrigatória para jogos UWP, mas recomendamos implementá-la em todos os jogos do XBOX, incluindo jogos do Microsoft Game Development Kit (GDK). Isso garante a portabilidade futura do seu título.
Configurar userAuthorizationStyle como true altera readRestriction e joinRestriction da sessão para local em vez de none. Isso significa que os títulos devem usar identificadores de pesquisa ou de transferência para ingressar em uma sessão de jogo.
Você pode definir essas capacidades no modelo de sessão ao configurar seus serviços do XBOX.
Para a navegação de sessões multiplayer, crie identificadores de pesquisa somente em sessões usadas para a jogabilidade real. Não os use em sessões de lobby.

Propriedade da sessão de jogo

Muitos tipos de sessão de jogo, como o SmartMatch ou uma sessão somente para amigos, não exigem um host ou proprietário. No entanto, ao configurar jogos de navegação de sessões multiplayer, talvez você queira um proprietário. Ter uma sessão gerenciada pelo proprietário traz alguns benefícios para o host, como remover outros membros da sessão ou alterar o status de propriedade de outros membros. Para usar proprietários em uma sessão, a sessão deve ter hasOwners definido como true. Ao usar Funções no multiplayer, você pode configurar para que somente os proprietários possam atribuir funções aos usuários.
Se um proprietário de uma sessão tiver bloqueado um membro do XBOX, esse membro não poderá ingressar na sessão.
Se todos os proprietários saírem de uma sessão, o serviço agirá sobre a sessão com base na política ownershipPolicy.migration definida para a sessão. Se a política for “oldest”, o usuário que está na sessão há mais tempo será definido como o novo proprietário. Se a política for “endsession” (o padrão, se nenhuma for fornecida), o serviço encerrará a sessão e removerá todos os usuários restantes da sessão.

Identificadores de pesquisa

Um identificador de pesquisa é armazenado no MPSD como uma estrutura JSON. Além de conter uma referência à sessão, os identificadores de pesquisa também contêm metadados adicionais para pesquisas, conhecidos como atributos de pesquisa. Uma sessão só pode ter um identificador de pesquisa criado para ela por vez. Para criar um identificador de pesquisa para uma sessão usando a XBOX Services API (XSAPI), chame o método XblMultiplayerCreateSearchHandleAsync.

Atributos de pesquisa

Os atributos de pesquisa consistem nos componentes a seguir.
  • As tags são descritores de cadeia de caracteres que as pessoas podem usar para categorizar uma sessão de jogo, como uma hashtag.
    • As tags devem começar com uma letra, não podem conter espaços e devem ter menos de 100 caracteres.
    • Tags de exemplo: “ProRankOnly”, “norocketlaunchers”, “cityMaps”.
  • As strings são variáveis de texto.
    • Os nomes das strings devem começar com uma letra, não podem conter espaços e devem ter menos de 100 caracteres.
    • Metadados de string de exemplo: “Weapons”=“knives+pistols+rifles”, “MapName”=“UrbanCityAssault”, “description”=“Fun casual game, new people welcome.”
  • Os numbers são variáveis numéricas. As XSAPIs recuperam valores numéricos como o tipo float.
    • Os nomes dos números devem começar com uma letra, não podem conter espaços e devem ter menos de 100 caracteres.
    • Metadados numéricos de exemplo: “MinLevel” = 25, “MaxRank” = 10.
O uso de maiúsculas e minúsculas nas tags e nos valores de string é preservado no serviço, mas você deve usar a função tolower() ao consultar tags. Isso significa que, no momento, as tags e os valores de string são todos tratados como minúsculos, mesmo que contenham caracteres maiúsculos.
Nas XSAPIs, você pode definir os atributos de pesquisa, como tags e metadados, usando o método XblMultiplayerCreateSearchHandleAsync.

Detalhes adicionais

Ao recuperar um identificador de pesquisa, os resultados também incluem dados úteis sobre a sessão, como se a sessão está fechada e se há restrições de entrada. Nas XSAPIs, esses detalhes, junto com os atributos de pesquisa, são incluídos nos resultados XblMultiplayerSearchHandle retornados após uma consulta de pesquisa.

Remover um identificador de pesquisa

Quando quiser remover uma sessão da navegação de sessões multiplayer, como quando a sessão está cheia ou fechada, você pode excluir o identificador de pesquisa. Nas XSAPIs, remova um identificador de pesquisa usando o método XblMultiplayerDeleteSearchHandleAsync.

Criar um identificador de pesquisa com metadados

O código a seguir mostra como criar um identificador de pesquisa para uma sessão usando as APIs multiplayer do XBOX.

API C simples

Para obter mais informações sobre as funções usadas no exemplo de código, consulte multiplayer_c.

Criar uma consulta de pesquisa de sessões

Ao recuperar uma lista de identificadores de pesquisa, você pode usar uma consulta de pesquisa para restringir os resultados às sessões que atendem a critérios específicos. A sintaxe da consulta de pesquisa é no estilo OData, com suporte apenas aos operadores a seguir.
Você também pode usar expressões lambda e a função canônica tolower.
No momento, não há suporte para nenhuma outra função OData. Ao pesquisar tags ou valores de string, você deve usar a função tolower na consulta de pesquisa. O serviço só oferece suporte à pesquisa de cadeias de caracteres em minúsculas. O serviço do XBOX retorna apenas os primeiros 100 resultados que correspondem à consulta de pesquisa. Garanta que os usuários possam refinar a consulta de pesquisa se os resultados forem muito amplos.
Instruções OR lógicas são compatíveis com consultas de cadeia de caracteres de filtro.
No entanto, apenas um OR é permitido, e ele deve estar na raiz da consulta. Você não pode ter várias instruções OR na consulta, nem criar uma consulta que resulte em OR não estar no nível mais alto da estrutura da consulta.

Exemplos de consulta de identificadores de pesquisa

Em uma chamada RESTful, “Filter” é onde você especifica uma cadeia de caracteres na linguagem OData Filter que é executada na consulta em todos os identificadores de pesquisa. Nas APIs do Multiplayer 2015, você pode especificar a cadeia de caracteres do filtro de pesquisa usando o parâmetro searchFilter do método XblMultiplayerGetSearchHandlesAsync. No momento, há suporte para os cenários de filtro a seguir.

Atualizando os resultados da pesquisa

Seu jogo deve evitar atualizar automaticamente uma lista de sessões. Dê ao usuário a opção de atualizar a lista manualmente por meio da interface do usuário. Isso é útil se o usuário refinar os critérios de pesquisa para filtrar melhor os resultados. Se um usuário tentar ingressar em uma sessão, mas essa sessão estiver cheia ou fechada, seu jogo também deverá atualizar os resultados da pesquisa.
Atualizações de pesquisa em excesso podem levar à limitação do serviço.
Seu título deve limitar a frequência com que a consulta pode ser atualizada. Para reduzir o volume de chamadas ao serviço, os identificadores de pesquisa incluem propriedades de sessão personalizadas que podem ser usadas para armazenar e consultar atributos de sessão que mudam rapidamente. Esses atributos não devem ser armazenados nos atributos de pesquisa.

Consultar identificadores de pesquisa

O código a seguir mostra como consultar identificadores de pesquisa. A API retorna uma coleção de objetos XblMultiplayerSearchHandle que representam todos os identificadores de pesquisa que correspondem à consulta.

API C simples

Para obter mais informações sobre as funções usadas no exemplo de código, consulte multiplayer_c.

Ingressar em uma sessão usando um identificador de pesquisa

Depois que um usuário recuperar um identificador de pesquisa de uma sessão na qual deseja ingressar, garanta que ele possa se adicionar à sessão usando XblMultiplayerWriteSessionByHandleAsync.
Os métodos XblMultiplayerWriteSessionAsync não podem ser usados para ingressar em uma sessão de navegação de sessões multiplayer.
Última modificação em 8 de outubro de 2026