Documentation Steamworks
Statistiques et succès

Présentation

Avec les stats et les succès Steam, votre jeu peut facilement fournir à vos utilisateurs un suivi persistant et accessible partout de leurs statistiques et succès. Les données de l'utilisateur sont associées à son compte Steam et les succès et statistiques de l'utilisateur peuvent tous être formatés et affichés dans son profil de la communauté Steam.

Avantages des stats et succès

En plus de fournir des récompenses de grande valeur aux joueurs de vos jeux, les succès permettent d'encourager et de récompenser le travail d'équipe et l'interaction entre les joueurs, offrent une dimension supplémentaire aux objectifs du jeu et récompensent les utilisateurs pour avoir passé plus de temps dans le jeu.

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 auprès de l'utilisateur sur plusieurs ordinateurs).

Présentation de l'implémentation

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

Les succès sont spécifiques à chaque application et sont paramétrés sur la page d'administration de l'application sur le 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 ex. nombre de km que le joueur a conduit).
  • AVGRATE : moyenne variable. Voir 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 pour l'API : chaîne 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 Stats de serveurs de jeu.
  • Uniquement croissant : si ce paramètre est défini, la valeur de cette stat 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 stat 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 stat. 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 stat pour un nouvel utilisateur. S'il n'est pas défini, la valeur par défaut est zéro.
  • Total : si ce paramètre est défini, Steam conservera un total global pour cette stat. Consultez les stats mondiales ci-dessous pour plus d'informations.
  • Nom affiché : nom de cette stat, tel qu'il s'affiche sur la communauté Steam. Peut être localisé.
Les stats 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.

Les succès ont les propriétés suivantes :
  • ID : identifiant numérique automatiquement généré pour chaque succès.
  • Nom pour l'API : chaîne utilisée pour accéder à ce succès via l'API.
  • Stat. de progression : spécifie une stat utilisée comme barre de progression dans la communauté pour ce succès. Le succès sera automatiquement déverrouillé lorsque la stat aura atteint la valeur de déblocage.
  • Nom affiché : nom que portera le succès dans les fenêtres de notification du client et dans la communauté. Peut être localisé.
  • Description : description de ce succès, pour affichage sur la communauté. Peut être localisée.
  • Défini par : définit qui peut déverrouiller le succès. Par défaut, c'est le client. Pour en savoir plus, consultez Stats de serveurs de jeu.
  • Caché : si ceci vaut true, le succès ne s'affichera pas sur la page de l'utilisateur dans la communauté (pas du tout) tant qu'il ne l'aura pas déverrouillé.
  • Icône « débloqué » : icône à afficher quand le succès est obtenu.
  • Icône « verrouillé » : icône à afficher quand le succès n'a pas encore été obtenu.

Voici la liste des succès dans l'exemple du jeu Spacewar consultable ici :
achievements_spacewar.png

Comment utiliser les stats et succès

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

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 approche consisterait à avoir deux statistiques : « PointsTotaux » de type INT et « HeuresDeJeuTotales » de type FLOAT, puis de diviser les points par le temps pour obtenir les points par heure.

L'inconvénient de cette solution est qu'une fois que le joueur a cumulé un temps de jeu important, la moyenne calculée change extrêmement lentement. En fait, plus l'utilisateur joue au jeu, moins cette moyenne sera réactive. Si l'utilisateur a passé 100 heures sur le jeu, la moyenne calculée aura un retard d'environ 50 heures par rapport à ce chiffre. Si l'utilisateur améliore ses compétences, il ne verra pas l'augmentation des points par heure à laquelle il 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 précédentes de jeu afin que la statistique reflète plus justement le niveau de compétence actuel du joueur.

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 cela :
  • Remarquez que, puisque la moyenne sera par heure, les unités de temps sur les paramètres temporels associés à cette statistique seront en heures. Ceci s'applique aux propriétés de la fenêtre dans la statistique elle-même et également au paramètre dSessionLength passé à UpdateAvgRateStat ci-dessous.
  • Créez une statistique de type AVGRATE nommée PointsMoyParHeure et une propriété Fenêtre de 20.0 (n'oubliez pas que les unités sont des heures).
  • À des moments appropriés de votre jeu, appelez ISteamUserStats::UpdateAvgRateStat avec les paramètres suivants :
    • pchName : "PointsMoyParHeure"
    • flCountThisSession : nombre de points que le joueur a gagnés depuis le dernier appel de UpdateAvgRateStat.
    • dSessionLength : temps de jeu depuis le dernier appel de UpdateAvgRateStat. L'unité doit être la même que celle de la propriété Fenêtre de la statistique. Dans notre cas, ce sont des heures.
  • Par exemple, si le joueur a gagné 77 points dans la dernière manche qui a duré 0,255 heure (13,5 minutes), on aura SteamUserStats()->UpdateAvgRateStat( "PointsMoyParHeure", 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 du joueur. Si la statistique était mise à jour pour la première fois pour l'utilisateur actuel, 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 comme pour la propriété Fenêtre.

Obtenir des stats pour d'autres utilisateurs

Vous pouvez utiliser ISteamUserStats::RequestUserStats pour obtenir les statistiques d'un autre utilisateur. Vous pouvez ensuite utiliser ISteamUserStats::GetUserStat, ISteamUserStats::GetUserAchievement et ISteamUserStats::GetUserAchievementAndUnlockTime pour obtenir les données de cet utilisateur. Ces données ne sont pas mises à jour automatiquement quand l'autre utilisateur télécharge de nouvelles stats. Donc, pour actualiser les données, appelez simplement ISteamUserStats::RequestUserStats à nouveau.

Pour éviter d'utiliser trop de mémoire, un cache des entrées les moins récemment utilisées (LRU) est conservé et les stats d'autres utilisateurs seront parfois déchargées. Quand cela se produit un rappel ISteamUserStats::UserStatsUnloaded_t est automatiquement envoyé. Quand ce rappel est envoyé, les stats de l'utilisateur spécifié ne seront plus disponibles jusqu'à ce que ISteamUserStats::RequestUserStats soit appelée à nouveau.

Mode hors-ligne

Steam conserve un cache local contenant les données de stats et de succès pour que les API puissent être utilisées normalement en mode hors ligne. Toutes les stats qui ne peuvent pas être remises sont sauvegardées pour la prochaine fois que l'utilisateur 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 stats affichant la plus grande progression. Étant donné que Steam conserve les données des stats dans un cache local, il n'est pas nécessaire pour le jeu de conserver également les données dans un autre cache local sur le disque. De tels caches entrent souvent en conflit et, lorsque c'est le cas, l'utilisateur peut avoir l'impression que sa progression n'a pas été enregistrée, ce qui peut s'avérer très frustrant.

Stats de serveurs de jeu

En parallèle de ISteamUserStats on trouve ISteamGameServerStats pour les serveurs de jeu. Ces fonctions permettent d'obtenir des stats pour les utilisateurs de la même manière que les clients (comme décrit plus haut). Elles peuvent aussi définir des stats et accorder des succès, mais uniquement si « Défini par » est configuré 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. Utiliser des serveurs de jeu officiels pour définir des stats permet une sécurité accrue contre la triche, car les utilisateurs peuvent modifier leurs propres serveurs de jeu ou se faire passer pour un serveur de jeu. Pour définir des serveurs de jeu officiels, saisissez la plage d'adresses IP des serveurs ici.

Les stats 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 stats et des succès que pour les utilisateurs qui jouent actuellement sur le serveur. Si l'utilisateur quitte le serveur, une courte période de grâce permet de définir toute stat finale, mais ensuite, tout nouveau téléchargement sera refusé. Ceci permet d'aider à assurer une meilleure uniformité et d'éviter la possibilité pour un serveur de jeu malveillant de définir les stats de qui que ce soit à tout moment. Étant donné cette restriction, il est important de ne pas attendre la fin d'une manche pour définir des stats. Définissez-les de manière continue afin de pouvoir les stocker lorsque l'utilisateur quitte le jeu.

Les clients vont recevoir des mises à jour automatiques lorsqu'un serveur de jeu changera ses stats. Toutefois, comme pour les clients, les stats chargées par le serveur pour d'autres utilisateurs ne sont pas actualisées automatiquement et peuvent devenir obsolètes.

Réinitialisation des stats

Pendant le développement, il arrive souvent qu'une réinitialisation des stats et des succès sur un compte ou sur tous les comptes soit nécessaire à des fins de test. Pour réinitialiser les stats d'un compte, appelez ISteamUserStats::ResetAllStats en affectant la valeur true à bAchievementsToo pour effacer aussi les succès. Une fois la fonction appelée, n'oubliez pas de réitérer le calcul de vos stats et succès et de réinitialiser l'état de votre jeu en mémoire. Il n'existe aucun moyen de réinitialiser globalement les stats et les succès de tous les utilisateurs. 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 de créer un système de réinitialisation globale dans votre jeu. Pour cela :
  • Définissez une stat avec un nom comme Version.
  • Définissez un numéro de version des stats codé en dur dans le jeu.
  • Une fois les stats chargées, comparez la stat Version avec votre numéro de version codé en dur.
  • Si elles ne concordent pas, appelez ISteamUserStats::ResetAllStats et affectez au numéro de version codé en dur la stat Version.
Ainsi, chaque fois que vous voulez faire une réinitialisation globale, changez simplement le numéro de version des stats codé en dur. La réinitialisation globale sera effectuée quand les utilisateurs obtiendront la nouvelle version.

Cohérence des stats

En règle générale, il faut toujours garder à l'esprit que des stats liées peuvent devenir incohérentes. Par exemple, imaginons que vous ayez trois stats « PartiesGagnées », « PartiesPerdues » et « PartiesJouées ». Malgré tous vos efforts, ces stats peuvent et vont être désynchronisées les unes par rapport aux autres. Dans ce cas, il peut arriver que la somme des parties gagnées et perdues ne soit pas égale au total de parties jouées. Si on résout ce problème en supprimant la stat PartiesPerdues et qu'on calcule à la place PartiesJouées - PartiesGagnées, une incohérence pourrait conduire à une valeur de PartiesPerdues négative. Dans ce cas, il vaut mieux abandonner la stat PartiesJouées et la calculer comme la somme PartiesGagnées + PartiesPerdues.

Stats mondiales

Les stats peuvent être marquées comme globales sur la page d'administration pour dire à Steam de conserver un total global des valeurs de tous les utilisateurs pour la statistique. Ceci peut être utilisé pour obtenir des données sur la somme totale d'argent dans l'économie, le nombre total de victimes, les armes préférées, les cartes préférées et quelle équipe a tendance à faire mieux. Par contre, ceci ne devrait pas être utilisé pour des stats du genre LePlusDeVictimes, car additionner ce chiffre sur plusieurs utilisateurs n'aurait aucun sens. Comme les stats sont entre les mains des utilisateurs, ces données sont susceptibles d'être manipulées. Il est donc crucial, lorsque vous utilisez des stats globales, de définir de bonnes limites pour les propriétés « valeur min. » et « valeur max. », « uniquement croissant » (le cas échéant) et « variation max. ». La variation maximum a une signification spéciale pour les stats globales. Lorsqu'une nouvelle valeur est téléchargée, la valeur globale ne changera pas plus que la valeur de la variation maximum. Ceci permet de limiter la vitesse à laquelle un tricheur peut influencer les totaux généraux.

Pour accéder aux totaux globaux, appelez ISteamUserStats::RequestGlobalStats et ensuite ISteamUserStats::GetGlobalStat pour chaque statistique globale. Vous pouvez aussi demander un nombre de jours d'historique spécifié à ISteamUserStats::RequestGlobalStats. L'historique correspond à la variation en valeur de la statistique chaque jour. Vous pouvez accéder à cet historique grâce à ISteamUserStats::GetGlobalStatHistory.

Vous pouvez aussi demander les pourcentages globaux de progression des succès au client. Pour cela, appelez d'abord ISteamUserStats::RequestGlobalAchievementPercentages. Ensuite, parcourez les succès dans l'ordre de la progression la plus complète à la moins complète en appelant ISteamUserStats::GetMostAchievedAchievementInfo et ISteamUserStats::GetNextMostAchievedAchievementInfo. Vous pouvez également obtenir le pourcentage d'achèvement pour un succès particulier en appelant ISteamUserStats::GetAchievementAchievedPercent.

La 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 aura un lien dans son profil de la communauté menant vers une page affichant ce qu'il a réussi et ce qui lui reste à déverrouiller.
REMARQUE : vos succès ne seront pas affichés tant que votre app ne sera pas visible de la communauté.

Chaque succès est listé avec l'icône appropriée, ainsi que le nom et la description 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, alors ils apparaîtront dans cette langue.

Il y aura également un lien depuis cette page, et un autre depuis la page Steam principale de votre jeu, vers l'ensemble des statistiques de succès globales pour votre jeu. Elle affiche le pourcentage de joueurs Steam qui ont obtenu chacun des succès de votre jeu, en partant du plus commun jusqu'au plus rare. Les joueurs apprécient de les voir et c'est en plus une excellente ressource pour vous en tant que développeur : vos défis spéciaux sont-ils assez difficiles ? Ou trop difficiles ? (Ces informations sont également disponibles sur le site des rapports de ventes et d'activations.)

D'autres questions ?

Vous pouvez poser vos questions sur le forum de discussion Stats and Achievements discussion board.