Aller plus loin avec les classements

Dans ce tutoriel, nous allons aborder les fonctionnalités avancées offertes par le service, comme la création de classements à plusieurs colonnes, le départage amélioré des égalités et les multiples façons d’interroger le classement. Pour cet exemple, nous supposons que tout ce qui est présenté dans Créer un classement de base vous est familier. Nous allons commencer avec un jeu de tir hautement compétitif comme exemple de la façon dont ces nouvelles fonctionnalités peuvent nous aider à résoudre certains problèmes. Dans ce jeu, il existe un mode appelé Team Death match, dans lequel deux équipes s’affrontent. La première équipe à atteindre 75 éliminations gagne. Or, ce jeu ne se base pas sur un seul score pour classer les joueurs; il se base plutôt sur le nombre d’éliminations, d’assistances et de morts pour déterminer qui est le meilleur.

Création d’une définition de classement à plusieurs colonnes

Pour commencer cet exemple, nous devons créer une définition de classement plus complexe que celle que nous avions auparavant. Nous allons définir plusieurs colonnes pour représenter les aspects clés du jeu : les éliminations, les assistances et les morts. 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 = "Eliminations",
                SortDirection = LeaderboardSortDirection.Descending,
            },
            new LeaderboardColumn()
            {
                Name = "Assists",
                SortDirection = LeaderboardSortDirection.Descending,
            }
            new LeaderboardColumn()
            {
                Name = "Deaths",
                SortDirection = LeaderboardSortDirection.Ascending,
            }         
        }
    };

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

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

SizeLimit : Ce paramètre sert à limiter le nombre de rangées que le classement peut comporter. La valeur indiquée ici n’est qu’un exemple.
VersionConfiguration : Ce paramètre nous permet de gérer des versions de nos classements. Consultez cette page pour plus d’information : Classements saisonniers
Columns : Ce paramètre nous permet de définir plusieurs colonnes, jusqu’à un maximum de 5 par définition. Comme vous pouvez le voir, nous avons configuré Eliminations, Assists et Deaths. Un élément important ici est le paramètre SortDirection, qui nous permet de déterminer le tri du classement. Dans cet exemple, un joueur est mieux classé s’il a plus d’éliminations et d’assistances (SortDirection = Descending) et moins de morts (SortDirection = Ascending).

Pour plus d’information sur les autres paramètres ou sur la gestion des définitions de classements, consultez Créer un classement de base.

Utiliser des entités externes

Le service Leaderboard peut être utilisé comme composant autonome et prend en charge l’utilisation d’entités externes qui n’ont de sens que dans le contexte du jeu. Si les identités de vos joueurs ne sont pas liées à la connexion PlayFab, vous pouvez quand même utiliser le service Leaderboards. Le type d’entité des entrées du classement provenant de l’extérieur du système PlayFab doit être external. L’entityId correspond alors à l’identité du joueur dans votre système. Dans ces cas, toutes les entrées du classement doivent être des entités external.

Ajout de données à un classement

Maintenant que notre classement est créé, nous allons y ajouter des données. La principale différence par rapport à notre tutoriel précédent sur ce sujet est que nous devons maintenant ajouter trois scores différents dans la même rangée. L’exemple suivant montre comment ajouter des données à notre classement à l’aide du SDK C#.

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(), (score + 1).ToString(), (score + 2).ToString() },
                Metadata = "metadata",
            }
        },
        AuthenticationContext = context,
        LeaderboardName = leaderboardName,
    };

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

Une chose importante à noter est que le paramètre Scores reçoit trois valeurs. La longueur de la liste des scores précisée pour toute entrée doit correspondre au nombre de colonnes de la définition de classement. Chacune des valeurs doit être un entier 64 bits valide (la représentation sous forme de chaîne sert uniquement à garantir que tous les clients peuvent gérer des valeurs 64 bits).

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

Nous allons maintenant apprendre différentes façons d’interroger un classement. Chacune a un objectif précis, soit d’aider les développeurs à obtenir les joueurs dont ils ont besoin pour les afficher dans le jeu.

Obtenir le classement autour d’une entité

Cette façon particulière d’interroger le classement nous permet d’obtenir une section du classement proche d’une entité précise. Une façon concrète de voir ce scénario est lorsque nous avons un classement énorme et que nous voulons seulement afficher de l’information pertinente au joueur qui est actif dans le jeu. Si le joueur est en 1000e position, nous pouvons afficher ses voisins proches plutôt que les meilleurs joueurs. L’exemple suivant montre comment interroger un classement autour d’une entité à l’aide du SDK C#.

public static async Task<List<EntityLeaderboardEntry>> GetLeaderboardAroundEntity(PlayFabAuthenticationContext context, string leaderboardName, string entityId)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    GetLeaderboardAroundEntityRequest getLbRequest = new GetLeaderboardAroundEntityRequest()
    {
        LeaderboardName = leaderboardName,
        AuthenticationContext = context,
        Entity = new PlayFab.LeaderboardsModels.EntityKey()
        {
            Id = entityId,
            Type = EntityType
        },
        MaxSurroundingEntries = 20,
    };

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

}

L’élément le plus important ici est MaxSurroundingEntries, qui nous permet d’extraire du classement les entités classées autour d’une entité précise. Par exemple, si nous avons un joueur en 100e position et que nous utilisons MaxSurroundingEntries = 20, les joueurs de la 90e à la 110e position sont récupérés. Si le joueur est en tête du classement, les 20 premiers résultats sont récupérés. Si le joueur est au bas du classement, les 20 derniers résultats sont récupérés. Sauf pour les positions en tête et au bas du classement, l’API tente de s’assurer que l’entité autour de laquelle le classement est demandé se trouve au centre des positions récupérées.

Obtenir le classement pour des entités

Cette API nous offre une autre façon d’interroger le classement. Elle convient lorsque nous voulons rechercher plusieurs entités dans le classement et les trier. L’exemple suivant montre comment interroger un classement pour une liste d’entités à l’aide du SDK C#.

public static async Task<List<EntityLeaderboardEntry>> GetLeaderboardForEntities(PlayFabAuthenticationContext context, string leaderboardName, List<string> entityIds)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    GetLeaderboardForEntitiesRequest getLbRequest = new GetLeaderboardForEntitiesRequest()
    {
        LeaderboardName = leaderboardName,
        AuthenticationContext = context,
        EntityIds = entityIds,
    };

    PlayFabResult<GetEntityLeaderboardResponse> lbResponse = await leaderboardsAPI.GetLeaderboardForEntitiesAsync(getLbRequest);

    return lbResponse.Result.Rankings;
}

Obtenir les classements d’amis

Il peut arriver que des joueurs occasionnels viennent jouer à un jeu. Ils sont peut-être loin de la tête du classement, mais une compétition est en cours entre eux et leurs amis. Avec cette API, nous pouvons interroger le classement et trouver les amis du joueur.

public static async Task<List<EntityLeaderboardEntry>> GetFriendLeaderboardForEntity(PlayFabAuthenticationContext context, string leaderboardName, string entityId)
{
    PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
    GetFriendLeaderboardForEntityRequest getLbRequest = new GetFriendLeaderboardForEntityRequest()
    {
       LeaderboardName = leaderboardName,
       Entity = new PlayFab.LeaderboardsModels.EntityKey()
       {
           Id = entityId,
           Type = EntityType
       },
    };

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

Il existe plusieurs façons d’obtenir des amis à partir des services PlayFab. Pour plus d’information sur les paramètres disponibles, consultez Référence de l’API.

Départage amélioré des égalités

Dans notre exemple de jeu de tir hautement compétitif, il arrive que plusieurs joueurs aient le même nombre d’éliminations. Pour ces scénarios, nous avons besoin d’une autre façon de départager ces cas. C’est dans ce scénario que la fonctionnalité de départage amélioré entre en jeu. Lorsque vous créez une définition de classement, vous pouvez avoir plusieurs colonnes. L’ordre dans lequel vous les ajoutez détermine la façon dont nous allons trier et départager certains scénarios. Il existe un ordre de priorité selon lequel la première colonne ajoutée est la plus importante, puis la deuxième, et ainsi de suite. Dans notre exemple, cela signifie que lorsqu’il y a égalité dans les éliminations, le deuxième critère est le nombre d’assistances, et le dernier critère est le nombre de morts. Dans le cas extrême où l’égalité persiste toujours, l’horodatage est utilisé par défaut : celui qui a obtenu les scores en premier l’emporte. | Rang | ID d’entité | Éliminations| Assistances | Morts | LastUpdated
|----------------------|------------------------------------|-------------------|-------------------------- |1 | “player 3” | 103 |24 | 15|“2024-08-27T20:24:36.738Z” |2 | “player 2” | 102 | 30| 20 |“2024-08-27T20:24:29.251Z” |3 | “player 1” | 100 | 25 |18 |“2024-08-27T19:52:26.642Z”
|4 | “player 4” | 100 | 25 | 18 |“2024-08-27T20:24:44.552Z” |4 | “player 5” | 100 | 25 | 19 |“2024-08-27T20:25:47.552Z” Dans cet exemple, il y a égalité entre trois joueurs :

« player 5 » : Malgré le même nombre d’éliminations et d’assistances, ce joueur a plus de morts, ce qui signifie qu’il se trouve au bas du classement.
« player 4 » : Ce joueur a moins de morts que « player 5 » et autant que « player 1 », mais player 1 a obtenu ces chiffres en premier.
« player 1 » : Malgré les mêmes chiffres que « player 4 », ce joueur a été le premier à obtenir ce score dans le jeu; il est donc mieux classé dans ce scénario de départage.

Conclusions

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

Créer un classement à plusieurs colonnes.
Examiner les multiples façons d’interroger le classement.
Comprendre le mécanisme de départage amélioré des égalités.

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

Création d’une définition de classement à plusieurs colonnes

Utiliser des entités externes

Ajout de données à un classement

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

Obtenir le classement autour d’une entité

Obtenir le classement pour des entités

Obtenir les classements d’amis

Départage amélioré des égalités

Conclusions

Voir aussi

​Création d’une définition de classement à plusieurs colonnes

​Utiliser des entités externes

​Ajout de données à un classement

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

​Obtenir le classement autour d’une entité

​Obtenir le classement pour des entités

​Obtenir les classements d’amis

​Départage amélioré des égalités

​Conclusions

​Voir aussi

Création d’une définition de classement à plusieurs colonnes

Utiliser des entités externes

Ajout de données à un classement

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

Obtenir le classement autour d’une entité

Obtenir le classement pour des entités

Obtenir les classements d’amis

Départage amélioré des égalités

Conclusions

Voir aussi