Présentation

Steam prend en charge les classements persistants dont les entrées sont ordonnées automatiquement. Ces classements peuvent être utilisés pour afficher des classements mondiaux ou ceux de contacts dans votre jeu et sur la page Web de votre communauté. Chaque titre Steamworks peut créer jusqu'à 10 000 classements et chaque classement peut être récupéré immédiatement après l'insertion du score d'un joueur.

Pour chaque classement, un joueur peut avoir une seule entrée. Il n'y a aucune limite au nombre de joueurs par classement. Chaque entrée contient un score pour le classement (un int32) et, en option, jusqu'à 64 int32 de données associées. Les données associées peuvent être utilisées pour stocker des informations de jeu spécifiques relatives à la session de jeu qui a généré l'entrée de classement de l'utilisateur. Ces données ne sont pas triées ou analysées par Steam et sont remplacées lorsqu'une nouvelle entrée de classement est créée pour l'utilisateur.

Toutes les fonctions de classement se trouvent dans ISteamUserGameStats.h et deux exemples de classements ont été implémentés dans l'exemple de Steamworks. Il est également possible de consulter et d'administrer les classements pour votre jeu dans l'administration du jeu Steamworks.

Avant de commencer

Toutes les fonctions de classement asynchrones renvoient un handle vers un résultat d'appel d'API Steam. Vous trouverez de plus amples informations sur la façon de recevoir ces résultats dans la section « Résultat d'appel » du document « Premières étapes ».

Créer un classement

Les classements sont spécifiques aux applications et sont configurés sur la page d'administration du jeu sur le site des partenaires Steamworks ou via l'API.

Création via le Web

Vous pouvez créer et gérer les classements dans la page d'Administration de l'application sur Steamworks pour votre AppID en accédant à Statistiques et succès -> Classements.


Les champs suivants doivent être renseignés pour définir un classement :

• Nom : définissez un nom adéquat pour le développement interne.
  
• Nom dans la communauté : si le classement doit s'afficher dans le hub de la communauté, définissez le nom public à cet endroit. Si aucun nom n'est renseigné, le classement n'apparaitra pas.
  
• Méthode de tri : définissez l'ordre pour le tri du classement. Pour les classements basés sur les positions, utilisez l'ordre croissant. Pour les meilleurs scores, utilisez l'ordre décroissant.
  
• Type à afficher : détermine les types des données à afficher dans le classement. Sélectionnez Numérique, Secondes ou Millisecondes.
  
• Écritures : si cette option est définie sur Fiable, les scores de classement ne peuvent pas être définis par les clients et peuvent être définis uniquement via l'API Web SetLeaderboardScore. La valeur par défaut est false.
  
• Lectures : si cette option est définie sur Contacts, le jeu peut lire uniquement les scores de classement des contacts de l'utilisateur ; tous les scores peuvent toujours être lus par l'API Web. La valeur par défaut est false.

Création via l'API

Vous pouvez créer des classements pour votre jeu via la page d'Admin. de l'app sur Steamworks ou par programme en appelant ISteamUserStats::FindOrCreateLeaderboard. Dans Steam, tous les classements d'un titre Steamworks sont identifiés par un nom unique. Le nom du classement est utilisé uniquement à des fins d'identification dans l'API Steamworks et n'est pas présenté aux utilisateurs au sein de la communauté Steam. Quand vous créerez un classement, vous devrez choisir :

• une méthode de tri : k_ELeaderboardSortMethodAscending (la première entrée est l'utilisateur avec le score le plus petit) ou k_ELeaderboardSortMethodDescending (la première entrée est l'utilisateur avec le score le plus grand).
  
• un type à afficher : ELeaderboardDisplayType sert à décrire ce que représente le score du classement, et n'est utilisé par la communauté que pour formater les scores de classements à l'affichage.

Si vous choisissez de créer vos classements seulement via la page d'Administration de l'application, vous pouvez utiliser ISteamUserStats::FindLeaderboard pour récupérer un handle pour votre classement. FindLeaderboard et FindOrCreateLeaderboard sont des méthodes asynchrones et renvoient le handle de classement pour le classement spécifié via un résultat d'appel ISteamUserStats::LeaderboardFindResult_t.

Une fois le classement créé, vous pouvez modifier la méthode de tri et le type à afficher via la page d'Admin. de l'app. Quand vous appelez FindOrCreateLeaderboard pour un classement existant, les paramètres méthode de tri et type à afficher sont ignorés.

Charger un score

Pour charger un score de classement, appelez simplement ISteamUserStats::UploadLeaderboardScore en passant le handle du classement cible (récupéré via FindLeaderboard), le score de l'utilisateur et, en option, toute donnée associée générée lorsque le nouveau score a été marqué. Si le score de classement de l'utilisateur est mis à jour, les données associées passées à ISteamUserStats::UploadLeaderboardScore remplaceront toute donnée précédemment stockée. Vous pouvez choisir entre deux méthodes de mise à jour quand vous chargez le score de classement d'un utilisateur :

• ISteamUserStats::k_ELeaderboardUploadScoreMethodKeepBest : Steam comparera le nouveau score de l'utilisateur avec son score déjà stocké dans le classement et gardera le meilleur score de l'utilisateur (le score le plus faible pour les classements avec un tri dans l'ordre croissant ; le score le plus élevé pour les classements avec un tri dans l'ordre décroissant).
  
• ISteamUserStats::k_ELeaderboardUploadScoreMethodForceUpdate : Steam remplacera systématiquement le score de l'utilisateur pour un classement par le nouveau score.
  
• ISteamUserStats::UploadLeaderboardScore est un appel asynchrone et le résultat du téléchargement est renvoyé dans un résultat d'appel LeaderboardScoreUploaded_t. Le résultat contient un marqueur indiquant si le score de l'utilisateur a changé, ainsi que les rangs mondiaux ancien et nouveau de l'utilisateur. Après leur chargement, les classements Steamworks sont immédiatement mis à jour pour refléter le nouveau score et le nouvel agencement des entrées peut être récupéré via DownloadLeaderboardEntries.

Joindre du contenu généré par les utilisateurs

Après avoir chargé un score, vous pouvez joindre du contenu généré par les utilisateurs pour l'entrée. Pour cela, appelez simplement ISteamUserStats::AttachLeaderboardUGC. Ce contenu peut être un replay de l'utilisateur qui réussit à atteindre le score ou un fantôme contre lequel on peut concourir. Le handle joint sera disponible lorsque l'entrée sera récupérée et peut être téléchargé par d'autres utilisateurs. Pour créer et télécharger un contenu généré par les utilisateurs, consultez la documentation de Steam Cloud.

Une fois joint, le contenu sera disponible même si le fichier du Cloud sous-jacent est modifié ou supprimé par l'utilisateur.

Récupérer des entrées de classement

Utilisez ISteamUserStats::DownloadLeaderboardEntries pour récupérer les entrées de classement à l'aide du handle de classement obtenu via ISteamUserStats::FindLeaderboard.

Après avoir récupéré avec GetDownloadedLeaderboardEntry toutes les entrées de classement téléchargées, les données d'entrée seront libérées et le handle SteamLeaderboardEntries_t dans LeaderboardScoresDownloaded_t ne sera plus valide.

Récupérer les informations de classement

Avec un handle de classement renvoyé par FindLeaderboard, vous pouvez récupérer les informations du classement à l'aide des fonctions suivantes :

ISteamUserStats::GetLeaderboardName
ISteamUserStats::GetLeaderboardEntryCount
ISteamUserStats::GetLeaderboardSortMethod
ISteamUserStats::GetLeaderboardDisplayType