Passer au contenu principal
Dans le XBOX Game Development Kit (GDK) et dans Steam, les succès comportent des informations comme le nom, la description, l’icône, le fait qu’ils aient été déverrouillés ou non pour l’utilisateur actuel et, facultativement, la progression vers leur obtention. Steam dispose également d’une API de statistiques utilisée par les jeux pour comparer la progression d’un utilisateur à une cible prédéterminée et déverrouiller des succès lorsque ces cibles sont dépassées. En fait, le XBOX Game Development Kit (GDK) dispose de deux API de succès : basée sur les événements (anciennement appelée Achievements 2013) et gérée par le titre (anciennement appelée Achievements 2017). Bien que les deux systèmes soient des options viables, les succès et statistiques gérés par le titre vous sembleront beaucoup plus familiers si vous venez de Steam et correspondront à la logique existante probablement présente dans votre jeu. C’est pourquoi nous décrirons cette API dans cette rubrique. Pour plus d’informations sur les différences entre les deux API, consultez Succès basés sur les événements et gérés par le titre. Les sections suivantes décrivent les différences entre les succès dans l’API Steamworks et dans le XBOX Game Development Kit (GDK). Pour utiliser les API de succès gérés par le titre, vous devez créer un handle de contexte des XBOX services. Pour ce faire, utilisez la fonction XblContextCreateHandle et un XUserHandle provenant de l’API XUserAddResult (voir la rubrique Authentification des utilisateurs et propriété).

Suivi de la progression des succès

Dans l’API Steam, vous pouvez utiliser l’API ISteamUserStats::GetStat/ISteamUser::SetStat pour suivre la progression d’un utilisateur vers un succès, ce qui fait des valeurs stockées dans l’API Steam Stats la source de vérité quant à la valeur de progression actuelle. Avec les succès gérés par le titre, votre jeu est l’unique source de vérité et doit suivre lui-même la progression actuelle de l’utilisateur. La mise à jour de la progression actuelle dans le nuage au moyen d’un appel d’API s’effectue comme une sorte de « point de contrôle » et sert à afficher la progression d’un utilisateur à certains endroits de l’écosystème XBOX. Il n’existe pas de directive précise sur l’emplacement où la valeur de progression actuelle doit être conservée, mais de nombreux jeux choisissent de la stocker dans leur fichier de sauvegarde (et dans le nuage), tandis que d’autres peuvent la stocker sur leur propre service dorsal. Assurez-vous de garder synchronisées les valeurs du nuage et celles du système interne de gestion des statistiques de votre jeu.

Énumération de tous les succès

Pour obtenir toutes les statistiques d’un utilisateur avec l’API Steamworks, vous appelez habituellement ISteamUserStats::RequestUserStats pour récupérer les dernières statistiques du serveur. Une fois le rappel correspondant déclenché, vous pouvez ensuite parcourir chaque succès par son nom d’API à l’aide des fonctions ISteamUserStats::GetStat/ISteamUserStats::GetAchievement et initialiser l’état du jeu à l’aide des données retournées. Avec le XBOX Game Development Kit (GDK), vous pouvez simplement utiliser la fonction XblAchievementsGetAchievementsForTitleIdAsync, puis utiliser les données de chaque objet de succès du tableau fourni comme paramètre de sortie de XblAchievementsResultGetAchievements pour initialiser l’état de votre jeu. Chaque succès est fourni sous forme de struct XblAchievement. Pour plus d’informations sur les données qu’elle contient, consultez sa rubrique de référence.

Steamworks

XBOX Game Development Kit (GDK)

Pour plus d’informations sur les succès gérés par le titre, consultez Obtention des succès gérés par le titre.

Mise à jour de la progression d’un succès et déverrouillage des succès

Dans le XBOX Game Development Kit (GDK) et dans Steam, c’est le code du jeu qui détermine quand un succès doit être déverrouillé. Avec le XBOX Game Development Kit (GDK), définir la progression d’un succès à 100 le déverrouille. Les sections suivantes décrivent les étapes requises pour mettre à jour la progression d’un utilisateur pour un succès donné avec les deux API. Voici un exemple de code pour une méthode UpdateAchievement, implémentée dans les deux SDK, qui reçoit un ID/nom d’API de succès (et un nom d’API de statistique dans Steam), la valeur d’incrémentation du succès et la valeur cible pour déverrouiller ce succès, puis met à jour la progression et l’état de déverrouillage du succès en conséquence.

Steamworks

XBOX Game Development Kit (GDK)

Pour plus d’informations sur les succès gérés par le titre, consultez Mise à jour des succès gérés par le titre.

Succès hors ligne

Le déverrouillage d’un succès XBOX ne nécessite pas de connexion réseau. Si l’utilisateur n’est pas connecté au réseau XBOX (également appelé XBOX Live), le succès se déverrouille automatiquement auprès du serveur plus tard, sans code supplémentaire.

Obtention des succès d’un autre utilisateur

Pour obtenir les succès d’un autre utilisateur, vous pouvez simplement appeler les fonctions XblAchievementsGetAchievementsForTitleAsync/XblAchievementsGetAchievementAsync avec l’ID d’utilisateur XBOX (XUID) de l’utilisateur dont vous voulez récupérer les succès. Cela est semblable à l’utilisation des fonctions ISteamUser::RequestUserStats, ISteamUserStats::GetUserStat et ISteamUserStats::GetUserAchievement dans Steam.

Réinitialisation des succès

Contrairement à ISteamUserStats::ResetAllStats de l’API Steamworks, qui peut servir à réinitialiser la progression de l’utilisateur pour toutes ses statistiques et, si cela est spécifié, ses succès, le XBOX Game Development Kit (GDK) n’offre aucune possibilité documentée de réinitialiser par programmation la progression ou l’état de déverrouillage des succès. Toute tentative d’appeler XblAchievementsUpdateAchievementAsync avec une valeur de progression de 0 laisse la valeur de progression inchangée. Toutefois, vous pouvez utiliser l’outil Player Data Reset (XblPlayerDataReset.exe) lors des tests pour y parvenir.

Limitation du débit

Lorsque vous mettez à jour la progression des succès, veillez à ne pas solliciter trop souvent l’API XBOX Services (XSAPI), car cela pourrait amener votre jeu à atteindre sa limite de débit. Cela peut entraîner un comportement inattendu et une mauvaise expérience pour vos utilisateurs. Pour les succès qui suivent des statistiques fréquemment mises à jour, essayez de regrouper les appels d’API afin qu’ils soient déclenchés après un certain nombre d’événements ou de mettre à jour le serveur à un intervalle de temps déterminé. Vous pouvez déboguer vos appels d’API à l’aide de l’XBOX services Trace Analyzer (XblTraceAnalyzer.exe). Pour plus d’informations sur la limitation du débit dans les XBOX services, consultez Limitation fine du débit.
Dernière modification le 6 octobre 2026