Suchen von Lobbies

Artikel
02/21/2024

Bei Titeln ist es oft nützlich, spielern die Suche nach Lobbies zu ermöglichen, die eine bestimmte Reihe von Kriterien wie Karte und Schwierigkeitsgrad neben anderen In-Game-Qualitäten erfüllen. Diese Suchfunktion ermöglicht es Spielern, die gewünschten Spielsitzungen mit den gewünschten Personen zu finden.

In diesem Artikel wird erläutert, wie Sie FindLobbies verwenden, um Spielern die Suche nach Lobbies zu ermöglichen. Informationen zum Ermitteln von Lobbies, die in Spieltiteln verwendet werden können, finden Sie unter Allgemeine Szenarien.

Notiz

Es wird nicht empfohlen, FindLobbies zum Implementieren von Hintergrundmatchmaking zu verwenden. Es wird dringend empfohlen, das Matchmaking-Feature in diesem Szenario zu verwenden. Andernfalls müssen Sie die Kollisionen von Spielern, die versuchen, den gleichen Lobbies beizutreten, durch Filtern, Sortieren und andere Techniken wie die Verwendung von Zufallswerten in Ihren Suchdatenfeldern behandeln.

Grundlegendes zur Beziehung zwischen Den Eigenschaften der Lobbysuche und der Suche nach Lobbies

Spieler machen ihre Lobbys auffindbar, indem sie Sucheigenschaften definieren. Spieler finden diese auffindbaren Lobbies, indem sie FindLobbies mit Abfragezeichenfolgen aufrufen, um ihre Suchergebnisse basierend auf den Sucheigenschaften zu filtern und zu sortieren, die in den derzeit aktiven Lobbies definiert sind. Lobbies, die diesen Abfragen entsprechen, werden an den aufrufenden Spieler zurückgegeben.

Weitere Informationen zum Definieren von Sucheigenschaften finden Sie unter Erstellen durchsuchbarer Lobbies.

Verwenden von FindLobbies

Wenn Sie FindLobbies aufrufen, können Sie den Filterparameter verwenden, um Ihre Abfrage so zu beschränken, dass nur Suchergebnisse zurückgegeben werden, die auf den benutzerdefinierten Sucheigenschaften des Wartebereichs basieren.

Darüber hinaus können Sie den Sortierparameter verwenden, um die Ergebnisse, die Sie vom Dienst erhalten, basierend auf den Sucheigenschaften zu sortieren. Dies ist nützlich, da der Dienst nur eine begrenzte Anzahl von Suchergebnissen zurückgibt. Durch die Sortierung wird sichergestellt, dass die relevantesten Suchergebnisse angezeigt werden.

Häufige Szenarien

Im Folgenden finden Sie einige gängige Methoden zur Verwendung der FindLobbies-Funktionalität in Titeln.

Suchen von Lobbies für Spielsitzungen für einen bestimmten Spielmodus in Ihrem Titel
Suchen von Lobbies für Spielesitzungen, die Ihre Freunde hosten
Finden von Lobbies für Spielsitzungen mit genügend Spielern für alle lokalen Spieler
Suchen nach Lobbies, in der Sie sich bereits befinden, um eine Verbindung nach einem unerwarteten Absturz des Spielclients oder Spielservers wiederherzustellen.

Unterstützte Suchschlüssel

Beim Definieren benutzerdefinierter Sucheigenschaften darf nur ein eingeschränkter Satz von Schlüsseln verwendet werden.

Für Zeichenfolgeneigenschaften werden die folgenden Schlüssel unterstützt: string_key1, string_key2, [...] string_key30
Für numerische Eigenschaften werden die folgenden Schlüssel unterstützt: number_key1, number_key2, [...] number_key30

Erstellen von Abfragezeichenfolgen für FindLobbies

Abfragezeichenfolgen für die FindLobbies-APIs sind in einer OData-ähnlichen Syntax strukturiert. Die maximale Größe für die Filterzeichenfolge beträgt 600 Zeichen.

Diese OData-Operatoren können zum Erstellen von Abfragezeichenfolgen verwendet werden. Bei den Operatoren wird die Groß-/Kleinschreibung beachtet.

Operatoren	Bedeutung	Beispiel
Eq	gleich	string_key1 eq 'CaptureTheFlag'
Lt	weniger als	number_key2 lt 10
Le	kleiner als oder gleich	number_key2 le 10
Gt	größer als	number_key3 gt 100
Ge	größer als oder gleich	number_key3 Ge 100
Ne	Ne	string_key1 ne 'CaptureTheFlag'
und	und	string_key1 eq 'CaptureTheFlag' und number_key2 lt 10

Notiz

Achten Sie beim Vergleichen von Zeichenfolgeneigenschaften darauf, den verglichenen Wert in einfache Anführungszeichen einzuschließen. Beispiel: "string_key1 eq 'SOME STRING VALUE'". Numerische Eigenschaften müssen nicht umschlossen werden.

Es gibt auch vordefinierte Operatoren, die verwendet werden können. Ihnen muss bei der Angabe "lobby/" vorangestellt werden.

Operatoren	Bedeutung	Beispiel
memberCount	Anzahl der Spieler in einer Lobby	lobby/memberCount eq 5
maxMemberCount	Maximal zulässige Anzahl von Spielern in einer Lobby	lobby/maxMemberCount gt 10
memberCountRemaining	Verbleibende Anzahl von Spielern, die der Lobby beitreten können	lobby/memberCountRemaining gt 0
membershipLock	lock status von Lobbies muss gleich "Unlocked" oder "Locked" sein.	lobby/membershipLock eq 'Unlocked'
amOwner	Lobbies, deren Besitzer Sie sind, müssen gleich "true" sein.	lobby/amOwner eq 'true'
amMember	Lobbies, deren Mitglied Sie sind, müssen gleich "true" sein.	lobby/amMember eq 'true'
amServer	Lobbies, denen der Server clienteigene Lobbies beigetreten ist, müssen gleich "true" sein.	lobby/amServer eq 'true'

Die SDK-Definition für diese Konstanten ist hier dokumentiert.

Sortieren

OData-Formatzeichenfolge, die die Sortierung für diese Abfrage in aufsteigender ("asc") oder absteigender ("desc") Reihenfolge enthält. OrderBy-Klauseln können für jeden der Suchnummernschlüssel oder die vordefinierten Suchschlüssel verwendet werden, die numerisch sind. Um nach einer Zahl am nächsten zu sortieren, kann ein Monikerabstand verwendet werden, um nach Entfernung vom angegebenen Zahlensuchschlüssel zu sortieren. Sie können bei der Entfernungssortierung nicht aufsteigend oder absteigend verwenden. Dieses Feld unterstützt nur eine Sortierklausel oder eine Distance-Klausel. Wenn keine Sortierung angegeben wird oder ein Tiebreak für die angegebene Sortierung erforderlich ist, wird die Standardsortierung basierend auf der Erstellungszeit absteigend sein.

Beispiel	Bedeutung
number_key1 asc	Aufsteigender Suchschlüssel nach Zahlenreihenfolge
lobby/memberCount desc	Absteigend nach Zahlen sortierter Suchschlüssel
distance(number_key1 = 5)	Sortieren nach Entfernung von der angegebenen Zahl
Standard	Reihenfolge nach Erstellungszeit absteigend

Beispiel für die Suche nach Lobbies mit dem Lobby and Matchmaking SDK

In diesem Beispiel möchte der Spieler alle Lobbies mit den folgenden Anforderungen finden:

Der Spielmodus ist "DeathMatch"
Der Wettbewerbsstil ist "Ranked"
Die Qualifikationsstufe des Spielers liegt innerhalb der mindest- und maximalen Qualifikationslimits der Lobby.

Darüber hinaus möchte der Spieler die Ergebnisse nach den folgenden Richtlinien sortiert haben:

Lobbies mit optimalen Qualifikationsstufen, die dem Skilllevel des Spielers am nächsten sind, sollten höher sortiert werden.

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
    }
}

Freigeben über