Erstellen einer einfachen Bestenliste

In diesem Tutorial zeigen wir Ihnen, wie Sie mit unserem neuen Bestenlistendienst eine einfache Bestenliste erstellen. Beginnen wir mit einem Beispiel für ein Arcade-Spiel, bei dem das Ziel darin besteht, so viele Feinde wie möglich zu besiegen, bis Sie besiegt sind. In diesem Fall wird Ihnen eine Bewertung zugewiesen. Nun möchten wir eine Bestenliste erstellen, um diesem Spiel zu helfen, zu bestimmen, wer der beste Spieler ist.

Erstellen einer Bestenliste

Der erste Schritt besteht darin, eine Bestenlistendefinition zu erstellen, die die Standard-Elemente für Rangfolgespieler enthält. Für unser Arcade-Spiel benötigen wir nur eine Spalte für die Punktzahl. Das folgende Beispiel zeigt, wie Sie die Bestenlistendefinition mithilfe des C#-SDK erstellen.

public static async Task CreateLeaderboardDefinitionAsync(PlayFabAuthenticationContext context, string leaderboardName)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    CreateLeaderboardDefinitionRequest leaderboardDefinitionRequest = new CreateLeaderboardDefinitionRequest()
    {
        AuthenticationContext = context,
        Name = leaderboardName,
        SizeLimit = 1000,
        EntityType = "title_player_account",
        VersionConfiguration = new VersionConfiguration()
        {
            MaxQueryableVersions = 1,
            ResetInterval = ResetInterval.Manual,
        },
        Columns = new List<LeaderboardColumn>()
        {
            new LeaderboardColumn()
            {
                Name = "arcadeScore",
                SortDirection = LeaderboardSortDirection.Descending,
            }          
        }
    };

    PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> createLbDefinitionResult = await leaderboardsAPI.CreateLeaderboardDefinitionAsync(leaderboardDefinitionRequest);
}

Lassen Sie uns nun einige wichtige Elemente dieses Beispiels erläutern:

• AuthenticationContext: Dieser Parameter verarbeitet die gesamte Authentifizierung hinter jeder Anforderung an unsere Dienste. Eine ausführliche Erläuterung finden Sie auf der folgenden Seite: Schnellstart-Bestenliste.
• Name: Dieser Parameter hilft Ihnen beim Identifizieren der Bestenlistendefinition. Es ist wichtig, hier etwas Relevantes auszuwählen, da es verwendet wird, um andere Anforderungen zum Abrufen von Informationen zu stellen. Darüber hinaus muss dieser Name eindeutig sein, sodass bei jeder Erstellung einer Bestenliste ein neuer Name verwendet werden sollte.
• EntityType: Dieser Parameter gibt den Entitätstyp an, für den Sie ihre Bestenliste erstellen möchten. Weitere Informationen finden Sie hier: Entity Programming Model.
  • title_player_acount: Dieser Entitätstyp bezieht sich auf Spieler in PlayFab. Um einen Spieler zu erstellen, können Sie die hier beschriebene Methode verwenden LoginAsPlayer : Schnellstart.
  • group: Diese Art von Entität bezieht sich auf eine Gruppe von Spielern, normalerweise gilt dieses Konzept in Spielen wie "Clans", "Gilden", usw. Weitere Informationen finden Sie hier: Gruppen-Bestenlisten.
  • external: Dieser Entitätstyp dient zum Hinzufügen benutzerdefinierter Daten zu unseren Bestenlisten. Jede Zeile muss an nichts in PlayFab gebunden sein, es handelt sich um Ihre eigenen Daten. Sie können ihre eigenen Bezeichner im EntityId Feld verwenden, solange es sich um Zeichenfolgen handelt.
  • master_player_account: Dieser Entitätstyp bezieht sich auf Spieler über Titel hinweg. Dieses Konzept gilt, wenn ein Studio über mehrere Titel verfügt und Spieler haben, die entweder von einem Titel zum anderen wechseln oder mehrere Titel aus demselben Studio spielen. Basierend auf diesem Konzept können Sie Bestenlisten von Spielern für mehrere Titel aus demselben Studio erstellen. Sie müssen folgendes verwenden: Die Konto-ID des Hauptspielers bezieht sich auch auf PlayFabId, um sie dem EntityIdzuzuordnen.
  • character: Diese Art von Entität bezieht sich auf Spiele mit einer Reihe von Charakteren, aus denen ein Spieler auswählen und seine Reise beginnen kann. Wenn Sie dieses Konzept im Hinterkopf haben, müssen Sie zuerst einen Spieler erstellen, um eine Bestenliste mit Charakteren zu erstellen, und dann können Sie einen Charakter erstellen, der diesem Spieler zugeordnet ist. Danach können Sie die CharacterId als Entitäts-ID verwenden und eine Zeile mit der entsprechenden Bewertung einfügen.
• VersionConfiguration: Mit diesem Parameter können Sie eine Versionierungsstrategie für Bestenlisten festlegen, die sich nach einem bestimmten Zeitraum selbst zurücksetzen. Dieses Konzept wird hier ausführlich behandelt: Saisonale Bestenlisten.
• Columns: Hier definieren wir die Anzahl der Spalten, die unsere Bestenliste haben wird. In diesem Beispiel legen wir nur eine Spalte für die Bewertung fest. Wir definieren auch als SortDirection absteigend, was bedeutet, dass der Spieler mit der höchsten Punktzahl an der Spitze stehen wird.

Mit all diesen Informationen können Sie nun das Beispiel ausführen und Ihre erste Bestenliste erstellen.

Abrufen einer Bestenlistendefinition

Vor dem Hinzufügen von Daten zu dieser Bestenliste möchten wir sicherstellen, dass sie ordnungsgemäß erstellt wurden. Um diese Aktion auszuführen, stellen wir ein Beispiel dafür bereit, wie Sie Ihre Bestenlistendefinition abrufen können.

public static async Task GetLeaderboardDefinition(PlayFabAuthenticationContext context, string leaderboardName)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    GetLeaderboardDefinitionRequest leaderboardDefReq = new GetLeaderboardDefinitionRequest()
    {
        Name = leaderboardName
    };

    PlayFabResult<GetLeaderboardDefinitionResponse> getleaderboardDefResult = await leaderboardsAPI.GetLeaderboardDefinitionAsync(leaderboardDefReq);
}

Um die Bestenlistendefinition abzurufen, geben Sie den Namen der erstellten Bestenliste an. Wenn Sie über mehrere Bestenlistendefinitionen verfügen, können Sie das nächste Beispiel verwenden, um einen Satz davon abzurufen.

 public static async Task ListLeaderboards(PlayFabAuthenticationContext context)
 {
     PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
     ListLeaderboardDefinitionsRequest listLbRequest = new ListLeaderboardDefinitionsRequest()  
     {
         AuthenticationContext = context,                
     };
     PlayFabResult<PlayFab.LeaderboardsModels.ListLeaderboardDefinitionsResponse> lbResponse = await leaderboardsAPI.ListLeaderboardDefinitionsAsync(listLbRequest);
    
 }

Aktualisieren einer Bestenlistendefinition

Wenn Sie Ihre Bestenlistendefinition aktualisieren möchten, können Sie dies wie folgt tun:

 public static async Task UpdateLeaderboardDefinitionAsync(PlayFabAuthenticationContext context, string leaderboardName, int sizeLimit, VersionConfiguration version)
 {
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    UpdateLeaderboardDefinitionRequest updateLbDefinitionRequest = new UpdateLeaderboardDefinitionRequest()
    {
        AuthenticationContext = context,
        Name = leaderboardName,
        SizeLimit = sizeLimit,
        VersionConfiguration = version,
     };
     PlayFabResult<PlayFab.ProgressionModels.EmptyResponse> updateLbDefinitionResult = await leaderboardsAPI.UpdateLeaderboardDefinitionAsync(updateLbDefinitionRequest);
           
 }

Beachten Sie, dass Spalten, EntityType und ResetInterval nicht als Teil des Updates geändert werden können.

Löschen der Bestenlistendefinition

Wenn Sie Ihre Bestenlistendefinition löschen möchten, können Sie dies wie folgt tun:

public static async Task DeleteLeaderboard(PlayFabAuthenticationContext context, string leaderboardName)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    DeleteLeaderboardDefinitionRequest deleteLbRequest = new DeleteLeaderboardDefinitionRequest()
    {
        AuthenticationContext = context,
        Name = leaderboardName,
    };

    PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> lbResponse = await leaderboardsAPI.DeleteLeaderboardDefinitionAsync(deleteLbRequest);
}

Hinzufügen von Daten zu einer Bestenliste

Wenn wir mit unserem Arcade-Spielbeispiel fortfahren, wissen wir jetzt, wie wir eine Bestenlistendefinition erstellen, abrufen und bei Bedarf löschen. Unser nächster Schritt ist das Hinzufügen von Daten zu unserer Bestenliste.

Beachten Sie, dass es sich hierbei um entitätsbasierte Bestenlisten handelt, was bedeutet, dass es sich bei den Einträgen um Entitäten handelt. Wir unterstützen auch das Mitbringen eigener externer Identitäten, was unter Mehr mit Bestenlisten ausführlich erläutert wird.

In unserem spezifischen Beispiel verwenden wir den Entitätstyp title_player_account, sodass unsere Bestenliste mit Spielern gefüllt ist. Denken Sie jedoch daran, dass sie auch andere Entitätstypen verwenden können. Sie können sie sich hier ansehen: Verfügbare integrierte Entitätstypen.

Nun sehen wir uns an, wie wir unserer Bestenliste Daten hinzufügen können.

public static async Task UpdateLeaderboardForPlayer(PlayFabAuthenticationContext context, string leaderboardName, string entityId, int score)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    UpdateLeaderboardEntriesRequest updateLeaderboardRequest = new UpdateLeaderboardEntriesRequest()
    {
        Entries = new List<LeaderboardEntryUpdate>()
        {
            new LeaderboardEntryUpdate()
            {
                EntityId = entityId,
                Scores = new List<string> { score.ToString()}                
            }
        },
        AuthenticationContext = context,
        LeaderboardName = leaderboardName,
    };

    PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> updateResult = await leaderboardsAPI.UpdateLeaderboardEntriesAsync(updateLeaderboardRequest);
}

Lassen Sie uns nun einige wichtige Elemente dieses Beispiels erläutern:

• Entries: Dieser Parameter entspricht der tatsächlichen Zeile, die der Bestenliste hinzugefügt wurde. Es verfügt über eine EntityId- bei der es sich um eine Zeichenfolge handelt, die die Entität innerhalb der Bestenliste identifiziert. Da es sich bei diesem Dienst um eine eigenständige Komponente handelt, können Sie hier Ihre eigenen Bezeichner verwenden. Wenn Sie jedoch andere PlayFab-Dienste verwenden, sollte dieser Wert für alle Dienste konsistent sein.
• Scores: Dieser Parameter entspricht der Liste der Bewertungen, die Sie einer Entität hinzufügen können. Denken Sie daran, dass Bestenlisten mehr als eine Spalte enthalten können. Sie können diese Konzepte hier ausführlich überprüfen: Mehr mit Bestenlisten tun
• Name: Dieser Parameter entspricht dem Namen der Bestenliste, der beim Erstellen der Bestenlistendefinition festgelegt wurde.

Jetzt können Sie Ihrer Bestenliste Daten hinzufügen.

Abrufen von Daten aus einer Bestenliste

Lassen Sie uns eine kurze Zusammenfassung machen. An diesem Punkt haben Sie eine Bestenliste erstellt, alle Konfigurationsdetails überprüft und damit begonnen, Entitäten hinzuzufügen. Stellen wir uns nun vor, einige Spieler haben bereits damit begonnen, Ihr Spiel zu verwenden, alle mit beeindruckenden Ergebnissen. Wir wollen ermitteln, wer der beste Spieler ist. Im folgenden Beispiel wird gezeigt, wie diese Aktion ausgeführt wird.

public static async Task<List<EntityLeaderboardEntry>> GetLeaderboard(PlayFabAuthenticationContext context, string leaderboardName)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    GetEntityLeaderboardRequest getLbRequest = new GetEntityLeaderboardRequest()
    {
        LeaderboardName = leaderboardName,
        StartingPosition = 1,
        PageSize = 20,
        AuthenticationContext = context,
    };

    PlayFabResult<GetEntityLeaderboardResponse> lbResponse = await leaderboardsAPI.GetLeaderboardAsync(getLbRequest);
    
    return lbResponse.Result.Rankings;
}

Lassen Sie uns nun einige wichtige Elemente dieses Beispiels erläutern:

• StartingPosition: Dieser Parameter bezieht sich auf die Position, von der aus Sie mit der Abfrage von Daten beginnen möchten. In diesem Fall möchten wir den Top-Spieler, daher legen wir diesen Parameter auf 1 fest. Dieser Parameter funktioniert auch mit dem PageSize -Parameter, um die gesamte Bestenliste nach Bedarf abzufragen.
• PageSize: Dieser Parameter gibt an, wie viele Datensätze in dieser Anforderung abgerufen werden.
• Name: Dieser Parameter entspricht dem Namen der Bestenliste, der beim Erstellen der Bestenlistendefinition festgelegt wurde.

Krawattenbruch

Stellen wir uns nun vor, dass einige Spieler, die Ihr Spiel verwenden, kämpfen, um zu sehen, wer der Beste ist. Wir stehen vor einem Problem: Zwei Spieler haben die gleiche Punktzahl, weil sie die gleiche Anzahl von Feinden besiegt haben. Wer sollte also der Top-Spieler sein?

Um diese Frage zu beantworten, verfügen wir standardmäßig über eine einfache Richtlinie für den Abbruch. Wir wählen den besten Spieler basierend auf dem Zeitstempel aus, zu dem die Punktzahl erreicht wurde. Wer es zuerst geschafft hat, ist der Top-Spieler. Je nach Kontext des Spiels ist dies jedoch möglicherweise nicht ausreichend oder genau. Komplexere Features für Die Verknüpfung finden Sie unter : Mehr Mit Leaderboards tun.

In unserem aktuellen Beispiel würde die Rangfolge wie folgt lauten:

Rang	Entitäts-ID	Wert	LastUpdated
1	"Spieler 3"	103	"2024-08-27T20:24:36.738Z"
2	"Spieler 2"	102	"2024-08-27T20:24:29.251Z"
3	"Spieler 1"	100	"2024-08-27T19:52:26.642Z"
4	"Spieler 4"	100	"2024-08-27T20:24:44.552Z"

In diesem speziellen Beispiel weisen sowohl "Spieler 1" als auch "Spieler 4" die gleiche Punktzahl auf. Die Entscheidung, wer zuerst geht, hängt vom Zeitstempel ab. Da "Spieler 1" zuerst die Punktzahl erreicht hat, wird dies der Grund, warum ist oben.

Löschen von Bestenlistenzeilen

Ihre Bestenlisten funktionieren wie erwartet, und Sie haben eine Reihe von Spielern in Ihrem Spiel. Sie beginnen jedoch, ein ungewöhnliches Verhalten zu erkennen, da es scheint, dass einige Spieler betrügen, um an die Spitze der Bestenliste zu gelangen. Sie werden ein solches Verhalten nicht tolerieren, daher möchten Sie sie aus Ihren Bestenlisten entfernen. Im nächsten Beispiel sehen Sie, wie Sie Zeilen aus Der Bestenliste löschen.

public static async Task DeleteLeaderboardEntries(PlayFabAuthenticationContext context, string leaderboardName, List<string> entityIds)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    DeleteLeaderboardEntriesRequest leaderboardsDelReq = new DeleteLeaderboardEntriesRequest() {
        Name = leaderboardName,
        EntityIds = entityIds
    };

    PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> delLeaderboardDefResult = await leaderboardsAPI.DeleteLeaderboardEntriesAsync(leaderboardsDelReq);
}

Lassen Sie uns nun einige wichtige Elemente dieses Beispiels erläutern:

• EntityIds: Dieser Parameter ist die Liste der Entitäts-IDs, die Sie löschen möchten.
• Name: Dieser Parameter entspricht dem Namen der Bestenliste, der beim Erstellen der Bestenlistendefinition festgelegt wurde.

Schlüsse

In diesem Tutorial haben wir gelernt, wie die folgenden Vorgänge ausgeführt werden:

• Erstellen Sie eine Bestenliste.
• Überprüfen Sie die Konfiguration einer Bestenliste.
• Aktualisieren Sie die Konfiguration der Bestenliste.
• Löschen Sie die Konfiguration der Bestenliste.
• Füllen Sie die Bestenliste auf.
• Erfahren Sie, wie tie-breaking funktioniert.
• Löschen Sie Einträge in der Bestenliste.

Weitere Informationen

• Mehr Mit Bestenlisten.
• Saisonale Bestenlisten.
• Rangfolge der Spieler nach Statistiken.
• Fügen Sie Kontextdaten zu Bestenlisten hinzu.
• Gruppen-Bestenlisten.
• Manuelle Ebenen.
• API-Referenz.