Passer au contenu principal
Dans le XBOX Game Development Kit (GDK) comme dans Steam, les succès comportent des informations telles que le nom, la description, l’icône, l’indication de leur déverrouillage pour l’utilisateur actuel et, éventuellement, la progression vers leur obtention. Steam dispose également d’une API de statistiques que les jeux utilisent pour comparer la progression d’un utilisateur à une cible prédéfinie 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/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écrivons 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 services XBOX. Pour cela, utilisez la fonction XblContextCreateHandle et un XUserHandle provenant de l’API XUserAddResult (voir la rubrique Authentification et propriété des utilisateurs).

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é pour la valeur de progression actuelle. Avec les succès gérés par le titre, votre jeu est la source unique de vérité et doit suivre lui-même la progression actuelle de l’utilisateur. La mise à jour de la progression actuelle dans le cloud au moyen d’un appel d’API constitue une sorte de « point de contrôle » et sert à afficher la progression d’un utilisateur à différents endroits de l’écosystème XBOX. Il n’existe pas de recommandation précise sur l’emplacement de stockage de la valeur de progression actuelle, mais de nombreux jeux choisissent de la stocker dans leur fichier de sauvegarde (et dans le cloud), tandis que d’autres peuvent la stocker sur leur propre service back-end. Veillez à maintenir la synchronisation des valeurs entre le cloud et le système de gestion interne 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 généralement ISteamUserStats::RequestUserStats pour récupérer les dernières statistiques depuis le serveur. Une fois le rappel correspondant déclenché, vous pouvez parcourir chaque succès par son nom d’API à l’aide des fonctions ISteamUserStats::GetStat/ISteamUserStats::GetAchievement et initialiser l’état du jeu à partir des données renvoyées. Avec le XBOX Game Development Kit (GDK), vous pouvez simplement utiliser la fonction XblAchievementsGetAchievementsForTitleIdAsync, puis utiliser les données de chaque objet 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 la forme d’une 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) comme 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 sur 100 le déverrouille. Les sections suivantes décrivent les étapes nécessaires pour mettre à jour la progression d’un utilisateur sur un succès donné avec les deux API. Voici un exemple de code d’une méthode UpdateAchievement, implémentée dans les deux SDK, qui prend en entrée 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 déverrouille le 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 connexion

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 synchronise automatiquement avec le 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 utilisateur XBOX (XUID) de l’utilisateur dont vous souhaitez récupérer les succès. Cela revient à utiliser les fonctions ISteamUser::RequestUserStats, ISteamUserStats::GetUserStat et ISteamUserStats::GetUserAchievement dans Steam.

Réinitialisation des succès

Contrairement à ISteamUserStats::ResetAllStats de l’API Steamworks, qui permet de réinitialiser la progression de l’utilisateur sur toutes ses statistiques et, si cela est spécifié, sur ses succès, le XBOX Game Development Kit (GDK) n’offre aucune fonctionnalité documentée pour réinitialiser par programmation la progression ou l’état de déverrouillage des succès. 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) pendant les tests pour y parvenir.

Limitation du débit

Lors de la mise à jour de la progression des succès, veillez à ne pas solliciter trop souvent l’API des services XBOX (XSAPI), car votre jeu risque d’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 à intervalles réguliers. Vous pouvez déboguer vos appels d’API à l’aide de l’analyseur de traces des services XBOX (XblTraceAnalyzer.exe). Pour plus d’informations sur la limitation du débit des services XBOX, consultez Limitation du débit précise.
Dernière modification le 6 octobre 2026