Classements de groupes

Dans ce didacticiel, nous allons apprendre à utiliser des entités de groupe dans un classement. Pour comprendre ce concept, nous allons partir de l’exemple d’un jeu « RPG » axé sur la terraformation de planètes. En tant que joueur, vous devez construire et développer des structures sur chaque planète, collecter des ressources, créer vos propres vaisseaux et également mettre en place des défenses, car d’autres joueurs pourraient vous attaquer pour voler vos biens. Un aspect clé de ce jeu est que les joueurs peuvent former des alliances dans le but de créer une équipe et d’attaquer d’autres joueurs en groupe. Dans ce contexte, nous voulons créer un classement pour les alliances, afin de savoir quelle est l’alliance la plus puissante de tout l’univers. Quelques points clés à garder à l’esprit avant d’approfondir le fonctionnement des classements de groupes :

Pour en savoir plus sur le modèle de programmation des entités, consultez : Modèle de programmation des entités.
Découvrez le fonctionnement des groupes ici : Groupes.

Création d’un classement

Selon le jeu et le type de scénarios que vous allez rencontrer, vous allez très probablement créer plusieurs classements. Dans ce contexte particulier, nous voulons présenter deux scénarios différents pour ce jeu et la manière d’utiliser le service pour répondre à chacun d’eux.

Classements de joueurs

Dans cet exemple, des joueurs terraforment des planètes et gagnent des points d’expérience en effectuant certaines actions dans le jeu. Nous allons donc avoir un classement pour suivre cette expérience au niveau du joueur. Ce processus suit le même comportement que celui présenté dans d’autres didacticiels comme Créer un classement de base. Le point clé ici est que le paramètre EntityType doit être "title_player_account" afin que le classement soit réservé aux joueurs.

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 = "XP",
                SortDirection = LeaderboardSortDirection.Descending,
            }        
        }
    };

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

Passons maintenant à l’aspect du jeu présenté dans l’exemple : les alliances. Nous pouvons créer des alliances dans PlayFab à l’aide de l’entité "group". Cette entité de groupe nous fournit une structure que les joueurs peuvent rejoindre ; elle dispose également de rôles et d’autres fonctionnalités intéressantes qui facilitent ce type de scénarios dans les jeux. Pour créer le classement, deux points doivent être clairs.

Le paramètre EntityType doit être "group".
Ce classement est indépendant. L’ajout d’un score pour une alliance est donc un processus manuel distinct du classement des joueurs. Ce comportement permet de relier les scores aux joueurs de différentes manières, ou d’utiliser une nouvelle métrique applicable uniquement aux groupes.

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 = "group",
        VersionConfiguration = new VersionConfiguration()
        {
            MaxQueryableVersions = 1,
            ResetInterval = ResetInterval.Manual,
        },
        Columns = new List<LeaderboardColumn>()
        {
            new LeaderboardColumn()
            {
                Name = "Group XP",
                SortDirection = LeaderboardSortDirection.Descending,
            }        
        }
    };

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

Ajout de données au classement

Après avoir créé les deux classements, nous devons voir comment y ajouter des données. Comme mentionné dans l’exemple précédent, ces classements sont indépendants l’un de l’autre, ce qui permet au développeur d’appliquer une logique personnalisée sur le fonctionnement des scores des alliances (groupes).

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

Le code permettant d’ajouter des entrées au classement des joueurs ou au classement des groupes est le même dans ce scénario. Mais ce n’est pas toujours le cas, car nous pourrions avoir un classement de joueurs à cinq colonnes, puis un autre classement de groupes avec une seule colonne. Nous décrivons plus en détail les classements à plusieurs colonnes dans ce didacticiel : Aller plus loin avec les classements. Gardez toujours à l’esprit que vous devez fournir le bon EntityId au service. Si vous avez un classement de joueurs, les entités sont de type "title_player_account" ; si le classement est composé de groupes, vous devez fournir des entités de type "group.

Récupérer les données du classement

Pour obtenir les données du classement, toutes les options décrites dans Aller plus loin avec les classements sont disponibles, à l’exception de l’API GetFriendLeaderboard.

Nom d’affichage des classements de groupes

Enfin, une autre possibilité avec les classements de groupes consiste à définir le nom d’affichage avec le nom du groupe de l’entité. Ainsi, si vous avez une alliance appelée « Raiders », ce nom de groupe sera associé à l’entité via la propriété DisplayName.

public static async Task<CreateGroupResponse> CreateGroup(string groupName, PlayFabAuthenticationContext context)
{
    var request = new CreateGroupRequest
    {
        GroupName = groupName,
        AuthenticationContext = context
    };
    var response = await PlayFabGroupsAPI.CreateGroupAsync(request);

    SetDisplayNameRequest displayRequest = new SetDisplayNameRequest()
    {
        AuthenticationContext = context,
        DisplayName = groupName,
        Entity = new PlayFab.ProfilesModels.EntityKey()
        {
            Id = response.Result.Group.Id,
            Type = "group",
        },
    };

    PlayFabResult<SetDisplayNameResponse> updateNameResult = await PlayFabProfilesAPI.SetDisplayNameAsync(displayRequest);

    return response.Result;
}

Dans cet exemple, nous créons un groupe en appelant la méthode CreateGroupAsync. La première étape de cette exécution renvoie l’objet Group, que nous allons utiliser pour définir le nom d’affichage. Pour cela, nous associons le nom du groupe à l’entité à l’aide de l’objet SetDisplayNameRequest, puis nous exécutons la méthode PlayFabProfilesAPI.SetDisplayNameAsync.

Conclusions

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

Créer un classement de groupes.
Alimenter ce classement en données.
Récupérer le classement.
Modifier le displayName afin d’afficher le nom du groupe.

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

Classements de groupes

Création d’un classement

Classements de joueurs