Créer un classement de base

Dans ce tutoriel, nous vous montrons comment créer un classement de base à l’aide de notre nouveau service Leaderboard. Commençons par un exemple de jeu d’arcade dont l’objectif est de vaincre le plus d’ennemis possible jusqu’à ce que vous soyez vaincu. Lorsque cela se produit, un score vous est attribué. Nous voulons maintenant créer un classement pour aider ce jeu à déterminer qui est le meilleur joueur.

Création d’un classement

La première étape consiste à créer une définition de classement qui comprend les éléments principaux pour classer les joueurs. Pour notre jeu d’arcade, nous n’avons besoin que d’une seule colonne pour le score. L’exemple suivant montre comment créer la définition de classement à l’aide du SDK C#.

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

Expliquons maintenant certains éléments clés de cet exemple :

AuthenticationContext : Ce paramètre gère toute l’authentification derrière chaque requête envoyée à nos services. Pour une explication détaillée, vous pouvez consulter la page suivante : Démarrage rapide des classements.
Name : Ce paramètre vous aide à identifier la définition de classement. Il est important de choisir un nom pertinent, puisqu’il sert à effectuer d’autres requêtes pour récupérer de l’information. De plus, ce nom doit être unique; un nouveau nom doit donc être utilisé chaque fois qu’un classement est créé.
EntityType : Ce paramètre précise le type d’entité pour lequel vous voulez créer votre classement. Pour en savoir plus, consultez : Modèle de programmation d’entités.
- title_player_acount : Ce type d’entité fait référence aux joueurs dans PlayFab. Pour créer un joueur, vous pouvez utiliser la méthode LoginAsPlayer décrite ici : Démarrage rapide.
- group : Ce type d’entité fait référence à un groupe de joueurs; ce concept s’applique habituellement aux « clans », aux « guildes », etc. dans les jeux. Pour plus d’information, consultez : Classements de groupes.
- external : Ce type d’entité sert à ajouter des données personnalisées à nos classements. Chaque rangée n’a pas besoin d’être liée à quoi que ce soit dans PlayFab; il s’agit de vos propres données. Vous pouvez utiliser vos propres identifiants dans le champ EntityId, pourvu qu’il s’agisse de chaînes.
- master_player_account : Ce type d’entité fait référence aux joueurs de plusieurs titres. Ce concept s’applique lorsqu’un studio possède plusieurs titres et que des joueurs sont passés d’un titre à l’autre ou jouent à plusieurs titres du même studio. Selon ce concept, vous pouvez créer des classements de joueurs de plusieurs titres du même studio. Vous devez utiliser l’ID du compte de joueur principal, aussi appelé PlayFabId, pour le faire correspondre à EntityId.
- character : Ce type d’entité est lié aux jeux qui offrent une série de personnages parmi lesquels un joueur peut choisir pour commencer son aventure. Dans cette optique, pour créer un classement de personnages, vous devez d’abord créer un joueur, puis créer un personnage associé à ce joueur. Vous pouvez ensuite utiliser le CharacterId comme ID d’entité et insérer une rangée avec le score correspondant.
VersionConfiguration : Ce paramètre vous permet de définir une stratégie de gestion des versions pour les classements qui se réinitialisent après une certaine période. Ce concept est abordé en détail ici : Classements saisonniers.
Columns : Ici, nous définissons le nombre de colonnes que notre classement comportera. Dans cet exemple, nous ne définissons qu’une seule colonne pour le score. Nous définissons également SortDirection comme décroissant, ce qui signifie que le joueur ayant le score le plus élevé sera en tête. Le nombre maximal de colonnes permis par définition est de 5.

Avec toute cette information, vous êtes maintenant prêt à exécuter l’exemple et à créer votre premier classement.

Obtenir une définition de classement

Avant d’ajouter des données à ce classement, nous voulons nous assurer qu’il a été créé correctement. Pour ce faire, nous fournissons un exemple de la façon dont vous pouvez récupérer votre définition de classement.

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

Pour récupérer la définition de classement, précisez le nom du classement que vous avez créé. Si vous avez plusieurs définitions de classements, vous pouvez utiliser l’exemple suivant pour en obtenir un ensemble.

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

Mettre à jour une définition de classement

Si vous voulez mettre à jour votre définition de classement, vous pouvez le faire comme suit :

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

Notez que Columns, EntityType et ResetInterval ne peuvent pas être modifiés dans le cadre de la mise à jour.

Supprimer une définition de classement

Si vous voulez supprimer votre définition de classement, vous pouvez le faire comme suit :

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

Ajout de données à un classement

Pour poursuivre notre exemple de jeu d’arcade, nous savons maintenant comment créer une définition de classement, la récupérer et la supprimer au besoin. Notre prochaine étape consiste à commencer à ajouter des données à notre classement. Gardez à l’esprit qu’il s’agit de classements basés sur des entités, ce qui signifie que les entrées sont des entités. Nous prenons également en charge l’utilisation de vos propres identités externes, ce qui est abordé en détail dans Aller plus loin avec les classements. Dans notre exemple précis, nous utilisons le type d’entité title_player_account; notre classement est donc rempli de joueurs. Rappelez-vous toutefois qu’il existe d’autres types d’entités que vous pouvez aussi utiliser. Vous pouvez les consulter ici : Types d’entités intégrés disponibles. Voyons maintenant comment ajouter des données à notre classement.

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

Expliquons maintenant certains éléments clés de cet exemple :

Entries : Ce paramètre correspond à la rangée réellement ajoutée au classement. Il comporte un EntityId, soit une chaîne qui identifie l’entité dans le classement. Puisque ce service est un composant autonome, vous pouvez utiliser vos propres identifiants ici. Toutefois, si vous utilisez d’autres services PlayFab, cette valeur doit être cohérente dans tous les services.
Scores : Ce paramètre correspond à la liste des scores que vous pouvez ajouter à une entité. Rappelez-vous que les classements peuvent comporter plus d’une colonne. Vous pouvez approfondir ces concepts ici : Aller plus loin avec les classements
Name : Ce paramètre correspond au nom du classement défini lors de la création de la définition de classement.

Vous êtes maintenant prêt à ajouter des données à votre classement.

Récupération des données d’un classement

Faisons un bref récapitulatif. À ce stade, vous avez créé un classement, vérifié tous les détails de configuration et commencé à y ajouter des entités. Imaginons maintenant que certains joueurs ont déjà commencé à jouer à votre jeu, tous avec des scores impressionnants. Nous voulons déterminer qui est le meilleur joueur. Dans l’exemple suivant, nous vous montrons comment effectuer cette action.

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

Expliquons maintenant certains éléments clés de cet exemple :

StartingPosition : Ce paramètre fait référence à la position à partir de laquelle vous voulez commencer à interroger les données. Dans ce cas, nous voulons le meilleur joueur; nous définissons donc ce paramètre à 1. Ce paramètre fonctionne également avec le paramètre PageSize pour parcourir l’ensemble du classement au besoin.
PageSize : Ce paramètre précise le nombre d’enregistrements extraits dans cette requête.
Name : Ce paramètre correspond au nom du classement défini lors de la création de la définition de classement.

Départage des égalités

Imaginons maintenant que certains joueurs de votre jeu s’affrontent pour savoir qui est le meilleur. Nous faisons face à un problème : deux joueurs ont le même score parce qu’ils ont vaincu le même nombre d’ennemis. Alors, qui devrait être le meilleur joueur? Pour répondre à cette question, nous appliquons par défaut une politique de départage simple. Nous choisissons le meilleur joueur en fonction de l’horodatage auquel le score a été obtenu. Celui qui l’a obtenu en premier est le meilleur joueur. Toutefois, selon le contexte du jeu, cela pourrait ne pas être suffisant ou précis. Pour des fonctionnalités de départage plus complexes, consultez : Aller plus loin avec les classements. Dans notre exemple actuel, le classement serait le suivant :

Rang	ID d’entité	Score	LastUpdated
1	”player 3”	103	”2024-08-27T20:24:36.738Z”
2	”player 2”	102	”2024-08-27T20:24:29.251Z”
3	”player 1”	100	”2024-08-27T19:52:26.642Z”
4	”player 4”	100	”2024-08-27T20:24:44.552Z”

Dans cet exemple particulier, « player 1 » et « player 4 » ont le même score. La décision de savoir qui passe en premier repose sur l’horodatage. Puisque « player 1 » a obtenu le score en premier, c’est la raison pour laquelle il est en tête.

Suppression de rangées d’un classement

Vos classements fonctionnent comme prévu et vous avez beaucoup de joueurs dans votre jeu. Toutefois, vous commencez à remarquer un comportement inhabituel, car il semble que certains joueurs trichent pour atteindre le sommet du classement. Vous n’allez pas tolérer un tel comportement; vous voulez donc les retirer de vos classements. Dans l’exemple suivant, vous pouvez voir comment supprimer des rangées de votre classement.

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

Expliquons maintenant certains éléments clés de cet exemple :

EntityIds : Ce paramètre est la liste des ID d’entités que vous voulez supprimer.
Name : Ce paramètre correspond au nom du classement défini lors de la création de la définition de classement.

Conclusions

Dans ce tutoriel, nous avons appris à effectuer les opérations suivantes :

Créer un classement.
Vérifier la configuration d’un classement.
Mettre à jour la configuration du classement.
Supprimer la configuration du classement.
Remplir le classement.
Comprendre le fonctionnement du départage des égalités.
Supprimer des entrées du classement.

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

Créer un classement de base

Créer un classement de base

Création d’un classement

Obtenir une définition de classement

Mettre à jour une définition de classement

Supprimer une définition de classement

Ajout de données à un classement

Récupération des données d’un classement

Départage des égalités

Suppression de rangées d’un classement

Conclusions

Voir aussi

​Créer un classement de base

​Création d’un classement

​Obtenir une définition de classement

​Mettre à jour une définition de classement

​Supprimer une définition de classement

​Ajout de données à un classement

​Récupération des données d’un classement

​Départage des égalités

​Suppression de rangées d’un classement

​Conclusions

​Voir aussi

Créer un classement de base

Création d’un classement

Obtenir une définition de classement

Mettre à jour une définition de classement

Supprimer une définition de classement

Ajout de données à un classement

Récupération des données d’un classement

Départage des égalités

Suppression de rangées d’un classement

Conclusions

Voir aussi