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

# Localizar lobbies

> Pesquise PlayFab Lobbies públicos usando cadeias de caracteres de filtro e classificação em propriedades pesquisáveis, contagem de membros e ordenação por distância para a descoberta de lobbies.

Muitas vezes, é útil que os títulos permitam que os jogadores encontrem lobbies que atendam a um determinado conjunto de critérios, como mapa e nível de dificuldade, entre outras qualidades do jogo. Essa funcionalidade de pesquisa permite que os jogadores encontrem as sessões de jogo que desejam com as pessoas que desejam.

Este artigo explica como usar **FindLobbies** para permitir que os jogadores encontrem lobbies. Para ver como a localização de lobbies pode ser usada em títulos de jogos, consulte [Cenários comuns](#common-scenarios).

<Note>
  Não é recomendável usar **FindLobbies** para implementar matchmaking em segundo plano. Recomendamos fortemente usar o [recurso de matchmaking](/pt-BR/services/playfab/multiplayer/matchmaking) nesse cenário. Caso contrário, você precisará lidar com as colisões de jogadores que tentam ingressar nos mesmos lobbies por meio de filtragem, classificação e outras técnicas, como o uso de valores de randomização nos seus campos de dados de pesquisa.
</Note>

## Entender a relação entre as propriedades de pesquisa do lobby e a localização de lobbies

Os jogadores tornam seus lobbies detectáveis definindo propriedades de pesquisa. Os jogadores encontram esses lobbies detectáveis chamando **FindLobbies** com cadeias de caracteres de consulta para filtrar e classificar os resultados da pesquisa com base nas propriedades de pesquisa definidas nos lobbies ativos no momento. Os lobbies que correspondem a essas consultas são retornados ao jogador que fez a chamada.

Para obter mais informações sobre como definir propriedades de pesquisa, confira [Criar lobbies pesquisáveis](/pt-BR/services/playfab/multiplayer/lobby/define-search-keywords)

## Como usar FindLobbies

Ao chamar **FindLobbies**, você pode usar o parâmetro de filtro para restringir sua consulta e retornar apenas os resultados de pesquisa que correspondam a um conjunto de critérios com base nas propriedades de pesquisa personalizadas do lobby.

Além disso, você pode usar o parâmetro de classificação para classificar os resultados retornados pelo serviço com base nas propriedades de pesquisa. Isso é útil, pois o serviço retorna apenas um número limitado de resultados de pesquisa. A classificação garante que você veja os resultados de pesquisa mais relevantes.

<a id="common-scenarios" />

### Cenários comuns

Estas são algumas formas comuns de usar a funcionalidade **FindLobbies** nos títulos.

* Localizar lobbies de sessões de jogo de um modo de jogo específico do seu título
* Localizar lobbies de sessões de jogo que seus amigos estão hospedando
* Localizar lobbies de sessões de jogo com vagas suficientes para todos os jogadores locais
* Localizar lobbies nos quais você já está para recuperar uma conexão após uma falha inesperada do cliente ou do servidor de jogo.

### Chaves de pesquisa compatíveis

Somente um conjunto restrito de chaves pode ser usado ao definir propriedades de pesquisa personalizadas.

* Para propriedades de cadeia de caracteres, as seguintes chaves são compatíveis: string\_key1, string\_key2, \[...] string\_key30
* Para propriedades numéricas, as seguintes chaves são compatíveis: number\_key1, number\_key2, \[...] number\_key30

### Construir cadeias de caracteres de consulta para FindLobbies

As cadeias de caracteres de consulta das APIs **FindLobbies** são estruturadas em uma sintaxe semelhante ao OData. O tamanho máximo da cadeia de caracteres de filtro é de 600 caracteres.

Estes operadores OData podem ser usados para compor cadeias de caracteres de consulta. Os operadores diferenciam maiúsculas de minúsculas.

| Operadores | Significado | Exemplo |
| - | - | - |
| eq | igual a | string\_key1 eq 'CaptureTheFlag' |
| lt | menor que | number\_key2 lt 10 |
| le | menor ou igual a | number\_key2 le 10 |
| gt | maior que | number\_key3 gt 100 |
| ge | maior ou igual a | number\_key3 ge 100 |
| ne | diferente de | string\_key1 ne 'CaptureTheFlag' |
| and | e | string\_key1 eq 'CaptureTheFlag' and number\_key2 lt 10 |

<Note>
  Ao comparar propriedades de cadeia de caracteres, coloque o valor comparado entre aspas simples. Por exemplo, "string\_key1 eq **'SOME STRING VALUE'**". As propriedades numéricas não precisam de aspas.
</Note>

Também há operadores predefinidos disponíveis. Eles precisam ser prefixados com "lobby/" ao serem especificados.

| Operadores | Significado | Exemplo |
| - | - | - |
| memberCount | número de jogadores em um lobby | lobby/memberCount eq 5 |
| maxMemberCount | número máximo de jogadores permitidos em um lobby | lobby/maxMemberCount gt 10 |
| memberCountRemaining | número restante de jogadores que podem ingressar no lobby | lobby/memberCountRemaining gt 0 |
| membershipLock | status de bloqueio dos lobbies, deve ser igual a 'Unlocked' ou 'Locked' | lobby/membershipLock eq 'Unlocked' |
| amOwner | lobbies dos quais você é o proprietário, deve ser igual a 'true' | lobby/amOwner eq 'true' |
| amMember | lobbies dos quais você é membro, deve ser igual a 'true' | lobby/amMember eq 'true' |
| amServer | lobbies pertencentes ao cliente nos quais o servidor ingressou, deve ser igual a 'true' | lobby/amServer eq 'true' |

A definição do SDK para essas constantes está documentada [aqui](/pt-BR/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/constants/pflobbysearchkeys).

### Classificação

Cadeia de caracteres no estilo OData que contém a classificação desta consulta em ordem crescente ("asc") ou decrescente ("desc"). As cláusulas OrderBy podem ser usadas para qualquer uma das chaves numéricas de pesquisa ou das chaves de pesquisa predefinidas que são numéricas. Para classificar pela proximidade de um número, o moniker distance pode ser usado para classificar pela distância em relação à chave numérica de pesquisa especificada. Não é possível usar ordem crescente ou decrescente com a classificação por distância. Este campo só oferece suporte a uma cláusula de classificação ou a uma cláusula de distância. Se nenhuma classificação for fornecida ou se for necessário um desempate para a classificação especificada, a classificação padrão será decrescente com base no horário de criação.

| Exemplo | Significado |
| - | - |
| number\_key1 asc | ordenar pela chave numérica de pesquisa em ordem crescente |
| lobby/memberCount desc | ordenar pela chave numérica de pesquisa em ordem decrescente |
| distance\{number\_key1 = 5} | classificar pela distância em relação ao número especificado |
| *padrão* | ordenar pelo horário de criação em ordem decrescente |

## Exemplo de localização de lobbies usando o SDK de Lobby e Matchmaking

Neste exemplo, o jogador quer localizar todos os lobbies com os seguintes requisitos:

* O modo de jogo é "DeathMatch"
* O estilo de competição é "Ranked"
* O nível de habilidade do jogador está dentro dos limites mínimo e máximo de habilidade do lobby.

Além disso, o jogador quer os resultados classificados com as seguintes diretrizes:

* Lobbies com níveis de habilidade ideais mais próximos do nível de habilidade do jogador devem aparecer primeiro

```cpp theme={null}
static PFMultiplayerHandle g_pfmHandle = nullptr;

#define SUPPORT_XBL_CROSSPLAY

#define PFLOBBY_SEARCH_KEY_GAME_MODE "string_key1"
#define PFLOBBY_SEARCH_KEY_COMPETITION_STYLE "string_key2"
#define PFLOBBY_SEARCH_KEY_SKILL "number_key1"

#define GAME_MODE_DEATH_MATCH "DeathMatch"
#define COMPETITION_STYLE_RANKED "Ranked"

// Find lobbies based on player's search criteria.
void FindGamesWithRuntimeQuery(
    uint32_t minimumSkill,
    uint32_t maximumSkill,
    uint32_t optimalSkill)
{
    PFLobbySearchFriendsFilter friendsFilter;
    friendsFilter.includeSteamFriends = true;
#ifdef SUPPORT_XBL_CROSSPLAY
    friendsFilter.includeXboxFriendsToken = MyGame::GetLocalUserXboxToken();
#endif // SUPPORT_XBL_CROSSPLAY

    // Limit results based on friend's filter.
    PFLobbySearchConfiguration searchConfiguration = { 0 };
    searchConfiguration.friendsFilter = &friendsFilter;

    // Create filter string based on player's search parameters.
    std::string filterString;
    filterString += PFLOBBY_SEARCH_KEY_GAME_MODE + std::string(" eq ") + "'" + GAME_MODE_DEATH_MATCH + "'";
    filterString += " and ";
    filterString += PFLOBBY_SEARCH_KEY_COMPETITION_STYLE + std::string(" eq ") + "'" + COMPETITION_STYLE_RANKED + "'";
    filterString += " and ";
    filterString += PFLOBBY_SEARCH_KEY_SKILL + std::string(" ge ") + std::to_string(minimumSkill);
    filterString += " and ";
    filterString += PFLOBBY_SEARCH_KEY_SKILL + std::string(" le ") + std::to_string(maximumSkill);

    // Create sort string based on player's sort preference.
    std::string sortString;
    sortString += std::string("distance{") + PFLOBBY_SEARCH_KEY_SKILL + "=" + std::to_string(optimalSkill) + "}";

    searchConfiguration.filterString = filterString.c_str();
    searchConfiguration.sortString = sortString.c_str();

    HRESULT hr = PFMultiplayerFindLobbies(g_pfmHandle, &m_localUser, &searchConfiguration, nullptr);
}

void ProcessStateChanges()
{
    while (true)
    {
        uint32_t stateChangeCount;
        const PFLobbyStateChange* const* stateChanges;
        RETURN_VOID_IF_FAILED(PFMultiplayerStartProcessingLobbyStateChanges(
            g_pfmHandle,
            &stateChangeCount,
            &stateChanges));

        for (uint32_t i = 0; i < stateChangeCount; ++i)
        {
            const PFLobbyStateChange* stateChange = stateChanges[i];
            switch (stateChange->stateChangeType)
            {
                case PFLobbyStateChangeType::FindLobbiesCompleted:
                {
                    GuiPostCurrentLobbySearchResults(
                        static_cast<const PFLobbyFindLobbiesCompletedStateChange&>(*stateChange));
                    break;
                }
                default:
                {
                    break;
                }
            }
        }

        RETURN_VOID_IF_FAILED(PFMultiplayerFinishProcessingLobbyStateChanges(
            g_pfmHandle,
            stateChangeCount,
            stateChanges));
    }
}

// Update game UI to display search results when a list of matching lobbies is returned.
void GuiPostCurrentLobbySearchResults(
    const PFLobbyFindLobbiesCompletedStateChange& stateChange)
{
    if (FAILED(stateChange.result))
    {
        GuiToastErrorAndExitScreen();
        return;
    }

    for (uint32_t i = 0; i < stateChange.searchResultCount; ++i)
    {
        const PFLobbySearchResult& searchResult = stateChange.searchResults[i];
        GuiPostLobbySearchResultRow(searchResult); // defined elsewhere
    }
}
```

## Confira também

* [Criar lobbies pesquisáveis](/pt-BR/services/playfab/multiplayer/lobby/define-search-keywords)
* [Ingressar em lobbies](/pt-BR/services/playfab/multiplayer/lobby/join-lobbies)
* [Lobby e matchmaking](/pt-BR/services/playfab/multiplayer/lobby/lobby-and-matchmaking)
* [Propriedades do lobby](/pt-BR/services/playfab/multiplayer/lobby/lobby-properties)
* [Criar um lobby](/pt-BR/services/playfab/multiplayer/lobby/create-a-lobby)


## Related topics

- [Início rápido do plug-in Multiplayer para Unity](/pt-BR/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/multiplayer-unity-plugin-quickstart.md)
- [Convites de lobby](/pt-BR/services/playfab/multiplayer/lobby/lobby-invites.md)
- [Ingressar em lobbies](/pt-BR/services/playfab/multiplayer/lobby/join-lobbies.md)
- [Criar lobbies pesquisáveis](/pt-BR/services/playfab/multiplayer/lobby/define-search-keywords.md)
- [Propriedades personalizadas do PlayFab Lobby](/pt-BR/services/playfab/multiplayer/lobby/lobby-properties.md)