Présentation

Avec les statistiques et succès Steam, vous pouvez facilement fournir aux utilisateurs et utilisatrices de votre jeu un suivi de leurs statistiques et succès persistant et accessible partout. Leurs données sont associées à leur compte Steam et leurs succès et statistiques peuvent tous être formatés et affichés dans leur profil de la communauté Steam.

Avantages des statistiques et succès

En plus de fournir des récompenses précieuses aux joueurs et joueuses de vos jeux, les succès permettent d'encourager et de récompenser le travail d'équipe et les interactions en apportant une dimension supplémentaire aux objectifs du jeu et en récompensant les personnes qui passent davantage de temps à jouer à vos titres.

Les statistiques permettent de suivre des informations de détail, telles que le temps de jeu, le nombre d'améliorations utilisées, etc. Vous pouvez choisir de les utiliser simplement pour suivre les données internes du jeu (par exemple, pour pouvoir accorder un succès en fonction des statistiques de jeu multisession recueillies d'un compte jouant sur plusieurs ordinateurs).

Présentation de l'implémentation

Définir les statistiques et succès de votre jeu

Les succès sont spécifiques à chaque application et sont paramétrés sur la page Admin. de l'app du site des partenaires Steamworks.

Votre jeu peut stocker des statistiques de trois types :

• INT : entier 32 bits signé (par ex. nombre de parties jouées) ;
  
• FLOAT : flottant sur 32 bits (par exemple, le nombre de kilomètres parcourus) ;
  
• AVGRATE : moyenne variable. Voir Le type de statistique AVGRATE.

Le site Web des partenaires Steamworks fournit une interface pour définir et mettre à jour les statistiques et les succès de votre jeu. Elle vous permet de :

• définir les statistiques et les succès initiaux ;
  
• ajouter des stats et des succès supplémentaires ;
  
• mettre à jour les noms, les descriptions et les icônes des succès ;
  
• mettre à jour les paramètres et les contraintes (valeurs min/max, tailles des fenêtres de moyenne variable, etc.) des statistiques.

Les statistiques ont les propriétés suivantes.

• ID : identifiant généré automatiquement pour chaque statistique.
  
• Type : type de cette statistique (INT, FLOAT ou AVGRATE).
  
• Nom d'API : chaine de caractères utilisée pour accéder à cette statistique via l'API.
  
• Défini par : définit qui peut modifier la statistique. Par défaut, c'est le client. Pour en savoir plus, consultez Statistiques du serveur de jeu.
  
• Uniquement croissant : si ce paramètre est défini, la valeur de cette statistique ne peut qu'augmenter avec le temps.
  
• Variation max. : si ce paramètre est défini, il impose une limite à la variation de valeur de la statistique entre deux appels de SetStat.
  
• Valeur min. : si ce paramètre est défini, il indique la valeur numérique minimale que peut prendre cette stat. Par défaut, c'est le minimum du type numérique sous-jacent (INT_MIN ou -FLT_MAX).
  
• Valeur max. : si ce paramètre est défini, il indique la valeur numérique maximale que peut prendre cette statistique. Par défaut, c'est le maximum du type numérique sous-jacent (INT_MAX ou FLT_MAX).
  
• Valeur par défaut : si ce paramètre est défini, il s'agit de la valeur par défaut à laquelle sera initialisée la statistique pour un nouveau compte. S'il n'est pas défini, la valeur par défaut est zéro.
  
• Agrégé : si ce paramètre est défini, Steam conservera un total global pour cette statistique. Consultez les statistiques globales ci-dessous pour plus d'informations.
  
• Nom affiché : nom de cette statistique, tel qu'il s'affiche dans votre application.

Les statistiques de type AVGRATE ont les propriétés supplémentaires suivantes :

• Fenêtre : taille de la fenêtre glissante utilisée pour faire la moyenne de vos données.

Si une statistique est de type AVGRATE, sa moyenne est automatiquement calculée par Steam. Consultez la section AVGRATE ci-dessous pour plus d'informations.

Succès : consultez le guide étape par étape sur les succès.

Voici la liste des succès dans l'Exemple d'application utilisant l'API Steamworks (Spacewar) :

Considérations particulières

• Les noms de succès et des icônes doivent être appropriés pour tous les âges.
  
• Au début, les jeux sont limités à 100 succès par défaut. Une fois que l'application aura atteint le seuil pour les Fonctionnalités du profil, vous pourrez ajouter plus de succès.

Comment les utiliser

Accéder aux statistiques et aux succès depuis votre jeu :

• Après avoir initialisé l'API Steamworks, vous pouvez commencer à utiliser l'API Stats et succès contenue dans ISteamUserStats.
  
• Utilisez ISteamUserStats::GetStat et ISteamUserStats::GetAchievement pour itérer les données et initialiser l'état du jeu.
  
• Si vous souhaitez afficher les succès dans votre jeu, vous pouvez utiliser ISteamUserStats::GetAchievementDisplayAttribute pour récupérer les propriétés humainement lisibles d'un succès, comme son nom (« name ») et sa description (« desc »). Ces propriétés peuvent être traduites sur le site Web des partenaires Steamworks, et les données renvoyées varient en fonction de la langue dans laquelle la personne exécute le jeu. Vous pouvez également obtenir une icône de succès en utilisant ISteamUserStats::GetAchievementIcon ou l'heure à laquelle chaque succès a été débloqué avec ISteamUserStats::GetAchievementAndUnlockTime.
  
• Chaque fois qu'une statistique est modifiée, effectuez un appel ISteamUserStats::SetStat ou ISteamUserStats::UpdateAvgRateStat, notamment avant que tout changement ne soit visible du public. Ces appels ne modifient que l'état de la mémoire dans Steam et sont peu couteux. Cela permet à Steam de conserver les modifications entre chaque session, même si le jeu venait à rencontrer un problème.
  
• Profitez des moments propices dans votre jeu, tels que les points de sauvegarde automatique ou les transitions entre les niveaux pour appeler ISteamUserStats::StoreStats et mettre en ligne les changements. Vous recevrez un rappel de ISteamUserStats::UserStatsStored_t lorsque les données seront prêtes.
  
• Pour les succès qui disposent d'une barre de progression, utilisez ISteamUserStats::IndicateAchievementProgress aux points importants pour afficher une fenêtre de notification indiquant la progression. Par exemple, si le succès nécessite 20 victoires, vous pourriez effectuer cet appel à la 10ᵉ victoire pour signifier à la personne qu'elle est à la moitié de la progression.
  
• Chaque fois qu'un succès ou plus est débloqué, appelez ISteamUserStats::SetAchievement pour chaque succès déverrouillé, puis ISteamUserStats::StoreStats pour les mettre en ligne immédiatement. Votre jeu verra un rappel de ISteamUserStats::UserStatsStored_t, plus un rappel de ISteamUserStats::UserAchievementStored_t pour chaque succès déverrouillé. L'overlay Steam du jeu va afficher un panneau de notification à l'écran de l'utilisateur ou de l'utilisatrice.

Le type de statistique AVGRATE

Ce type de statistique fournit des fonctionnalités uniques et très utiles, mais nécessite quelques explications supplémentaires.

Imaginez que vous souhaitiez suivre une statistique moyenne, comme les « points gagnés par heure ». Une première approche consiste à avoir deux statistiques. Une INT « TotalPoints » et une FLOAT « TotalPlayTimeHours », puis de diviser le nombre de points par le temps pour obtenir les points par heure.

L'inconvénient de cette solution est qu'une fois que la personne a cumulé un certain temps de jeu, la moyenne calculée change extrêmement lentement. En fait, plus elle jouera au jeu, moins cette moyenne sera réactive. Une fois 100 heures passées sur le jeu, la moyenne calculée aura un retard d'environ 50 heures par rapport au nombre total. Si une personne améliore ses compétences, elle ne verra pas l'augmentation des points par heure à laquelle elle pourrait s'attendre.

Le type de statistique AVGRATE vous permet d'implémenter un effet de « fenêtre glissante » sur la moyenne. Par exemple, vous pouvez utiliser uniquement les quelques heures de jeu les plus récentes afin que la statistique reflète plus précisément le niveau de compétence actuel du joueur ou de la joueuse.

Mettons en place une statistique AVGRATE pour implémenter les « points par heure », où seules les 20 dernières heures de jeu affectent la valeur. Pour ce faire, suivez la marche ci-dessous.

• Remarque : puisque la moyenne sera « par heure », les unités de temps sur les paramètres associés à cette statistique seront en « heures ». Ceci s'applique à la propriété de la fenêtre dans la statistique elle-même et également pour le paramètre « dSessionLength » passé dans UpdateAvgRateStat ci-dessous.
  
• Créez une statistique AVGRATE nommée « AvgPointsPerHour » et une propriété de fenêtre de 20.0 (n'oubliez pas que les unités sont des « heures »).
  
• Aux moments appropriés durant le jeu, appelez ISteamUserStats::UpdateAvgRateStat avec les paramètres suivants :
  
  • pchName : « AvgPointsPerHour » ;
    
  • flCountThisSession : nombre de points que le joueur ou la joueuse a gagnés depuis le dernier appel de UpdateAvgRateStat ;
    
  • dSessionLength : le temps de jeu écoulé depuis le dernier appel de UpdateAvgRateStat. L'unité doit être la même que l'unité des propriétés de fenêtre de la statistique. On parle ici en « heures ».
    
• Par exemple, si la personne a obtenu 77 points lors de la dernière manche qui a duré 0,225 heure (13,5 minutes), on aura : SteamUserStats()->UpdateAvgRateStat( "AvgPointsPerHour", 77, 0.225 )

Dans l'exemple ci-dessus, Steam va prendre la moyenne des manches actuelles de 342,2 points par heure (77 divisé par 0,225) et la mélanger avec la valeur précédente. Le résultat va refléter la moyenne totale sur les 20 dernières heures de temps de jeu. Si la statistique était mise à jour pour la première fois pour ce compte, la valeur actuelle serait de 342,2.

Cet exemple utilise les « heures » comme unité de temps, mais vous pouvez utiliser l'unité que vous souhaitez. Pensez juste à utiliser la même unité partout, pour « dSessionLength » ainsi que dans les propriétés de la fenêtre.

Obtenir des statistiques pour les autres personnes

Vous pouvez utiliser ISteamUserStats::RequestUserStats pour obtenir les statistiques d'une autre personne. Vous pouvez ensuite utiliser ISteamUserStats::GetUserStat, ISteamUserStats::GetUserAchievement, et ISteamUserStats::GetUserAchievementAndUnlockTime pour obtenir les données de cette personne. Ces données ne sont pas mises à jour automatiquement quand l'autre personne met en ligne de nouvelles statistiques. Pour actualiser les données, vous devez donc simplement appeler à nouveau ISteamUserStats::RequestUserStats.

Pour éviter d'utiliser trop de mémoire, un cache des entrées les moins récemment utilisées (LRU) est conservé et les statistiques d'autres comptes seront parfois retirées. Lorsque cela se produit, un rappel ISteamUserStats::UserStatsUnloaded_t est envoyé automatiquement. Au moment de l'envoi de ce rappel, les statistiques de la personne en question seront indisponibles jusqu'à ce que ISteamUserStats::RequestUserStats soit de nouveau appelé.

Mode hors ligne

Steam conserve un cache local contenant les données de statistiques et de succès pour que les API puissent être utilisées normalement en mode hors ligne. Toutes les statistiques qui ne peuvent pas être validées sont sauvegardées pour la prochaine fois que la personne sera en ligne. Au cas où il y aurait eu des modifications sur plus d'une machine, Steam va automatiquement fusionner les succès et choisir l'ensemble de statistiques affichant la plus grande progression. Étant donné que Steam conserve les données des statistiques dans un cache local, il n'est pas nécessaire pour le jeu d'en faire de même dans un autre cache local sur le disque. De tels caches entrent souvent en conflit, donnant ainsi l'impression que la progression n'a pas été enregistrée, ce qui peut s'avérer très frustrant.

Statistiques du serveur de jeu

En parallèle de ISteamUserStats, on trouve ISteamGameServerStats pour les serveurs de jeu. Ces fonctions permettent d'obtenir des statistiques pour les comptes de la même manière que les clients (comme décrit plus haut). Elles peuvent aussi définir des statistiques et remettre des succès, mais uniquement si « Défini par » est défini sur GS (serveur de jeu) ou Official GS (serveur de jeu officiel). La différence entre les serveurs de jeu et les serveurs de jeu officiels est que ces derniers sont des serveurs que vous pouvez héberger et contrôler. L'utilisation de serveurs de jeu officiels pour définir des statistiques offre une sécurité accrue contre la triche, car il est possible que des personnes utilisant votre jeu modifient leurs propres serveurs de jeu ou se fassent passer pour un serveur de jeu. Pour définir des serveurs de jeu officiels, entrez les plages d'adresses IP des serveurs ici.

Les statistiques et les succès qui sont définissables par les serveurs de jeu ne peuvent pas être définis par les clients. Les serveurs de jeu ne peuvent définir des statistiques et des succès que pour les personnes qui jouent actuellement sur le serveur. Si l'une d'entre elles quitte le serveur, une courte période de grâce permet de définir toutes statistiques finales éventuelles, mais ensuite, toute nouvelle mises en ligne sera refusée. Cela garantit plus de cohérence et permet d'éviter le risque qu'un serveur de jeu malveillant ne définisse les statistiques de qui que ce soit à tout moment. À cause de cette restriction, il est important de ne pas attendre la fin d'une manche pour définir des statistiques. Définissez-les de manière continue afin de pouvoir les stocker lorsque quelqu'un quitte le jeu.

Les clients recevront des mises à jour automatiques lorsqu'un serveur de jeu modifiera leurs statistiques. Toutefois, comme les clients, les statistiques chargées par le serveur pour d'autres utilisateurs ou utilisatrices ne sont pas actualisées automatiquement et peuvent devenir obsolètes.

Réinitialisation des statistiques

Pendant le développement, il arrive souvent qu'une réinitialisation des statistiques et des succès sur un compte ou sur tous les comptes soit nécessaire à des fins de test. Pour réinitialiser les statistiques d'un compte, appelez ISteamUserStats::ResetAllStats avec bAchievementsToo défini sur true pour également réinitialiser les succès. Une fois la fonction appelée, n'oubliez pas de réitérer vos statistiques et vos succès et de réinitialiser l'état de votre jeu en mémoire. Il n'existe aucun moyen de réinitialiser globalement les statistiques et les succès de tous les comptes. L'une des raisons expliquant ceci est que, même si une réinitialisation globale devait être faite, les parties en cours pourraient ne pas remarquer la réinitialisation et réécrire les valeurs en mémoire. Heureusement, il existe un moyen simple d'intégrer un système de réinitialisation globale à votre jeu. Voici la marche à suivre.

• Définissez une statistique avec un nom comme « Version ».
  
• Définissez un numéro de version des statistiques codé en dur dans le jeu.
  
• Une fois que les statistiques ont été chargées, comparez la statistique « Version » avec votre numéro de version codé en dur.
  
• Si les deux valeurs ne correspondent pas, appelez ISteamUserStats::ResetAllStats puis définissez la statistique « Version » sur le numéro codé en dur.

Ainsi, chaque fois que vous voulez faire une réinitialisation globale, changez simplement le numéro de version des statistiques codé en dur. La réinitialisation globale sera effectuée quand les utilisateurs et utilisatrices obtiendront le nouveau build.

Cohérence des statistiques

En règle générale, il faut toujours garder à l'esprit que des statistiques liées peuvent devenir incohérentes. Imaginons que vous ayez trois statistiques : « GamesWon », « GamesLost » et « GamesPlayed ». Malgré tous vos efforts, ces statistiques peuvent et vont être désynchronisées les unes par rapport aux autres. Dans ce cas, il peut arriver que les parties gagnées et perdues ne s'additionnent pas au total de parties jouées. Si on résout ce problème en supprimant la statistique « GamesLost » et qu'on calcule à la place « GamesPlayed » - « GamesWon », une incohérence pourrait rendre une valeur de « GamesLost » négative. Dans ce cas, il vaut mieux abandonner la statistique « GamesPlayed » et la calculer comme « GamesWon » + « GamesLost ».

Statistiques globales

Vous pouvez indiquer que les statistiques doivent être agrégées sur la page d'Admin. de l'app pour dire à Steam de conserver un total global des valeurs de l'ensemble des joueurs et joueuses pour la statistique. Cette fonctionnalité sert à obtenir des données sur l'état de l'économie du jeu, le nombre total de victimes, les armes ou les cartes préférées, et quelle équipe a tendance à être la meilleure. Il ne faut cependant pas l'utiliser pour des statistiques du genre « MostKills », car additionner ce chiffre sur plusieurs comptes utilisateurs n'aurait aucun sens. Comme les statistiques sont entre toutes les mains, ces données sont sujettes à la manipulation. Il est donc crucial, lorsque vous utilisez des statistiques agrégées, de définir de bonnes limites de valeur min. et max., uniquement en incrémentation (si approprié) et la variation max. La variation max. a une signification particulière pour les statistiques agrégées. Lorsqu'une nouvelle valeur est mise en ligne, la valeur globale ne changera pas plus que la valeur de variation max. Cela permet de ralentir la vitesse à laquelle une personne qui triche peut influencer les statistiques globales.

Pour accéder aux stats globales, appelez ISteamUserStats::RequestGlobalStats puis ISteamUserStats::GetGlobalStat pour chaque statistique globale. Vous pouvez également appeler ISteamUserStats::RequestGlobalStats pour obtenir l'historique d'un nombre de jours spécifié. L'historique est la quantité quotidienne de changements subis par la statistique. Cet historique est accessible avec ISteamUserStats::GetGlobalStatHistory.

Vous pouvez aussi demander les pourcentages globaux de progression des succès auprès du client. Pour cela, appelez d'abord ISteamUserStats::RequestGlobalAchievementPercentages. Ensuite, itérez les succès dans l'ordre du plus avancé au moins avancé en termes de progression en appelant ISteamUserStats::GetMostAchievedAchievementInfo et ISteamUserStats::GetNextMostAchievedAchievementInfo. Il est également possible d'obtenir le pourcentage de progression d'un succès en particulier avec ISteamUserStats::GetAchievementAchievedPercent.

Tests

Les succès remportés ne seront visibles dans la communauté Steam ou dans la bibliothèque qu'après la publication de votre application. Votre application doit être en mesure d'indiquer aux utilisateurs et utilisatrices leurs succès obtenus.

Pour supprimer des statistiques ou un succès sans modifier le code de votre jeu, vous pouvez utiliser la console du client Steam. Exécutez-la avec steam.exe -console, suivi de :

• achievement_clear <appid> <achievement name>
  
• reset_all_stats <appid>

Communauté Steam

Après la sortie de votre jeu, les informations concernant la progression des succès individuels et globaux seront affichées dans la communauté Steam. Chaque joueur ou joueuse aura un lien dans son profil de la communauté menant vers une page affichant ses succès et ceux qu'il lui reste à débloquer.
Chaque succès est listé avec l'icône appropriée, ainsi que le nom et la description, comme définis dans le panneau de contrôle de Steamworks. Si le nom et la description du succès ont été localisés dans la langue choisie par l'utilisateur ou l'utilisatrice, alors ils apparaitront dans cette langue.

Il y aura également un lien dans cette page, et un autre dans la page Steam principale de votre jeu, vers un ensemble de statistiques globales des succès du titre. Pour chaque succès, le pourcentage de joueurs et joueuses Steam l'ayant obtenu sera affiché, en partant du succès le plus commun jusqu'au plus rare. Les fans apprécient, et c'est en plus une excellente ressource pour toute équipe de développement. Vos défis spéciaux sont-ils trop faciles ? Ou sont-ils au contraire trop difficiles ? (Cette information est également disponible sur le portail des rapports de ventes et d'activations.)

D'autres questions ?

Posez vos questions sur le forum de discussion consacré aux statistiques et aux succès.