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 l’exemple d’un jeu d’arcade dont l’objectif est de vaincre autant d’ennemis que possible jusqu’à ce que vous soyez vaincu. À ce moment-là, 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 inclut les éléments principaux permettant de 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 quelques éléments clés de cet exemple :

AuthenticationContext : ce paramètre gère toute l’authentification derrière chaque requête adressé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, car il est utilisé pour effectuer d’autres requêtes afin de récupérer des informations. En outre, ce nom doit être unique : un nouveau nom doit donc être utilisé chaque fois qu’un classement est créé.
EntityType : ce paramètre spécifie le type d’entité pour lequel vous souhaitez créer votre classement. Pour en savoir plus : Modèle de programmation d’entités.
- title_player_acount : ce type d’entité désigne les joueurs au sein de PlayFab. Pour créer un joueur, vous pouvez utiliser la méthode LoginAsPlayer décrite ici : Démarrage rapide.
- group : ce type d’entité désigne un groupe de joueurs ; ce concept s’applique généralement dans les jeux aux « clans », « guildes », etc. Pour plus d’informations, consultez : Classements de groupe.
- external : ce type d’entité permet d’ajouter des données personnalisées à nos classements. Chaque ligne 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 identificateurs dans le champ EntityId, à condition qu’il s’agisse de chaînes.
- master_player_account : ce type d’entité désigne les joueurs sur 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. Sur la base de ce concept, vous pouvez créer des classements de joueurs sur plusieurs titres du même studio. Vous devez utiliser l’ID de compte de joueur principal, également appelé PlayFabId, pour le mapper à l’EntityId.
- character : ce type d’entité concerne les jeux qui proposent 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. Ensuite, vous pouvez utiliser le CharacterId comme ID d’entité et insérer une ligne 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 traité en détail ici : Classements saisonniers.
Columns : nous définissons ici le nombre de colonnes que notre classement va comporter. Dans cet exemple, nous ne définissons qu’une seule colonne pour le score. Nous définissons également le 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 autorisées par définition est de 5.

Avec toutes ces informations, vous êtes maintenant prêt à exécuter l’exemple et à créer votre premier classement.

Obtention d’une définition de classement

Avant d’ajouter des données à ce classement, nous voulons nous assurer qu’il a été créé correctement. Pour cela, nous fournissons un exemple de récupération de 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, spécifiez le nom du classement que vous avez créé. Si vous avez plusieurs définitions de classement, 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);
    
 }

Mise à jour d’une définition de classement

Si vous souhaitez mettre à jour votre définition de classement, vous pouvez procéder 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 les colonnes (Columns), l’EntityType et le ResetInterval ne peuvent pas être modifiés dans le cadre de la mise à jour.

Suppression d’une définition de classement

Si vous souhaitez supprimer votre définition de classement, vous pouvez procéder 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 avec notre exemple de jeu d’arcade, nous savons maintenant comment créer une définition de classement, la récupérer et la supprimer si nécessaire. L’étape suivante 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 spécifique, nous utilisons le type d’entité title_player_account : notre classement est donc rempli de joueurs. N’oubliez pas toutefois qu’il existe d’autres types d’entités que vous pouvez également 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 quelques éléments clés de cet exemple :

Entries : ce paramètre correspond à la ligne effectivement ajoutée au classement. Il comporte un EntityId, qui est une chaîne identifiant l’entité dans le classement. Comme ce service est un composant autonome, vous pouvez utiliser vos propres identificateurs 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é. N’oubliez pas que les classements peuvent comporter plusieurs colonnes. Vous pouvez consulter ces concepts en détail 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é à utiliser votre jeu, tous avec des scores impressionnants. Nous voulons déterminer qui est le meilleur joueur. Dans l’exemple suivant, nous vous montrons comment procéder.

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 quelques éléments clés de cet exemple :

StartingPosition : ce paramètre désigne la position à partir de laquelle vous souhaitez commencer à interroger les données. Dans ce cas, nous voulons le meilleur joueur, nous définissons donc ce paramètre sur 1. Ce paramètre fonctionne également avec le paramètre PageSize pour parcourir l’ensemble du classement selon les besoins.
PageSize : ce paramètre spécifie le nombre d’enregistrements récupérés 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

Imaginons maintenant que certains joueurs de votre jeu s’affrontent pour savoir qui est le meilleur. Nous sommes confrontés à un problème : deux joueurs ont le même score, car ils ont vaincu le même nombre d’ennemis. Alors, qui doit être le meilleur joueur ? Pour répondre à cette question, nous appliquons par défaut une stratégie 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 peut 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	Dernière mise à jour
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. Comme « player 1 » a obtenu le score en premier, c’est la raison pour laquelle il est en tête.

Suppression de lignes de classement

Vos classements fonctionnent comme prévu et votre jeu compte de nombreux joueurs. Cependant, vous commencez à remarquer un comportement inhabituel : il semble que certains joueurs trichent pour atteindre le sommet du classement. Vous n’allez pas tolérer un tel comportement et vous souhaitez donc les supprimer de vos classements. L’exemple suivant montre comment supprimer des lignes 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 quelques éléments clés de cet exemple :

EntityIds : ce paramètre est la liste des ID d’entité que vous souhaitez 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.
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

Obtention d’une définition de classement

Mise à jour d’une définition de classement

Suppression d’une définition de classement

Ajout de données à un classement

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

Départage

Suppression de lignes de classement

Conclusions

Voir aussi

​Créer un classement de base

​Création d’un classement

​Obtention d’une définition de classement

​Mise à jour d’une définition de classement

​Suppression d’une définition de classement

​Ajout de données à un classement

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

​Départage

​Suppression de lignes de classement

​Conclusions

​Voir aussi

Créer un classement de base

Création d’un classement

Obtention d’une définition de classement

Mise à jour d’une définition de classement

Suppression d’une définition de classement

Ajout de données à un classement

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

Départage

Suppression de lignes de classement

Conclusions

Voir aussi