Introduction
Ce qui suit est un guide rapide pas à pas pour intégrer des classements Steam très basiques dans votre application en moins de 10 minutes. Le
SDK Steamworks est livré avec une excellente application exemple, appelée
Spacewar, qui démontre toute l'ampleur des fonctionnalités de Steam. Il est conseillé de commencer par là pour voir toutes les fonctionnalités de Steam en action. Ce didacticiel concentre les informations trouvées dans Spacewar et dans l'API des classements
ISteamUserStats, pour vous fournir seulement les informations nécessaires pour comprendre le fonctionnement des classements Steam.
Étape 1 : définir les classements de votre jeu
Les classements sont spécifiques à l'application et peuvent être configurés sur la page
Configuration des classements du site des partenaires Steamworks.
Les champs suivants doivent être renseignés pour définir un classement :
- Nom - Renseignez ce champ pour donner un nom approprié au 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 d'affichage - Détermine les types des données à afficher dans le classement. Sélectionnez parmi « Numériques », « Secondes » ou « Millisecondes ».
- Écritures - Si cette option est définie sur « Fiable », les scores des classements 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 ne pourra lire que les scores des classements des contacts de l'utilisateur. Tous les scores peuvent toujours être lus par l'API Web. La valeur par défaut est false.
Étape 2 : travail d'encapsulation des classements
Le code qui suit est indépendant du jeu et peut être ajouté à votre jeu si vous le jugez nécessaire. La classe est entièrement fonctionnelle en l'état, mais peut être facilement étendue pour répondre à d'autres besoins. Tout ce code est tiré directement des fichiers exemples de Spacewar
Leaderboards.cpp/h.
Fichier d'entête
Nous définissons une classe auxiliaire qui englobera tous les appels de l'API des classements Steam et qui créera tous les gestionnaires de résultats d'appel Steam.
class CSteamLeaderboards
{
private:
SteamLeaderboard_t m_CurrentLeaderboard; // handle vers le classement
public:
int m_nLeaderboardEntries; // Combien d'entrées avons-nous ?
LeaderboardEntry_t m_leaderboardEntries[10]; // Les entrées
CSteamLeaderboards();
~CSteamLeaderboards(){};
void FindLeaderboard( const char *pchLeaderboardName );
bool UploadScore( int score );
bool DownloadScores();
void OnFindLeaderboard( LeaderboardFindResult_t *pResult, bool bIOFailure);
CCallResult m_callResultFindLeaderboard;
void OnUploadScore( LeaderboardScoreUploaded_t *pResult, bool bIOFailure);
CCallResult m_callResultUploadScore;
void OnDownloadScore( LeaderboardScoresDownloaded_t *pResult, bool bIOFailure);
CCallResult m_callResultDownloadScore;
};
Fichier de code
Constructeur
Paramètres : aucun
Éléments renvoyés : sans objet
Action : ce constructeur initialise simplement les variables membres.
CSteamLeaderboards::CSteamLeaderboards() :
m_CurrentLeaderboard( NULL ),
m_nLeaderboardEntries( 0 )
{
}
FindLeaderboard()
Paramètres : identifiant de chaine du classement que vous voulez trouver (par exemple « Distance parcourue en pieds »).
Éléments renvoyés : rien
Action : cette méthode enveloppe un appel à
ISteamUserStats::FindLeaderboard. Cet appel vers Steam est asynchrone et demande un handle vers le classement donné. Cet appel doit être effectué avant que vous ne puissiez récupérer ou définir les entrées de classement. Cette méthode définit également la méthode de retour d'appel à utiliser.
void CSteamLeaderboards::FindLeaderboard( const char *pchLeaderboardName )
{
m_CurrentLeaderboard = NULL;
SteamAPICall_t hSteamAPICall = SteamUserStats()->FindLeaderboard(pchLeaderboardName);
m_callResultFindLeaderboard.Set(hSteamAPICall, this,
&CSteamLeaderboards::OnFindLeaderboard);
}
OnFindLeaderboard()
Paramètres : sans objet
Éléments renvoyés : rien
Action : cette méthode est un rappel qui est appelé chaque fois que nous essayons de trouver un classement sur Steam. Si le classement demandé est trouvé, nous définissons le handle de classement comme notre classement actuel.
void CSteamLeaderboards::OnFindLeaderboard( LeaderboardFindResult_t *pCallback, bool bIOFailure )
{
// voir si on a rencontré une erreur pendant l'appel
if ( !pCallback->m_bLeaderboardFound || bIOFailure )
{
OutputDebugString( "Impossible de trouver le classement\n" );
return;
}
m_CurrentLeaderboard = pCallback->m_hSteamLeaderboard;
}
UploadScore()
Paramètres : un int32 qui représente la valeur à stocker dans le classement actuel.
Éléments renvoyés : false si un classement n'a pas encore été sélectionné ; sinon true.
Action : cette méthode enveloppe un appel à
ISteamUserStats::UploadLeaderboardScore. Il s'agit d'un appel asynchrone vers Steam qui charge le score de l'utilisateur actuel dans le classement sélectionné. Cette méthode définit également la méthode de retour d'appel à utiliser. Cet appel doit être effectué après avoir sélectionné un classement avec
FindLeaderboard().
bool CSteamLeaderboards::UploadScore( int score )
{
if (!m_CurrentLeaderboard)
return false;
SteamAPICall_t hSteamAPICall =
SteamUserStats()->UploadLeaderboardScore( m_CurrentLeaderboard, k_ELeaderboardUploadScoreMethodKeepBest, score, NULL, 0 );
m_callResultUploadScore.Set(hSteamAPICall, this, &CSteamLeaderboards::OnUploadScore);
return true;
}
OnUploadScore()
Paramètres : sans objet
Éléments renvoyés : rien
Action : cette méthode est un rappel qui est appelé chaque fois que nous essayons de charger un score dans un classement sur Steam.
void CSteamLeaderboards::OnUploadScore(LeaderboardScoreUploaded_t *pCallback, bool bIOFailure)
{
if ( !pCallback->m_bSuccess || bIOFailure )
{
OutputDebugString( "Impossible de charger le score sur Steam\n" );
}
}
DownloadScores()
Paramètres : sans objet
Éléments renvoyés : false si un classement n'a pas encore été sélectionné, sinon true.
Action : cette méthode enveloppe un appel à
ISteamUserStats::DownloadLeaderboardEntries. Il s'agit d'un appel asynchrone vers Steam qui télécharge un ensemble d'entrées à partir du classement sélectionné. Dans ce cas, nous téléchargeons dix entrées : quatre avant l'utilisateur actuel, celle de l'utilisateur actuel et cinq après l'utilisateur actuel. Cet appel peut être modifié pour renvoyer n'importe quel nombre d'entrées à partir de n'importe quelle place du classement. Cette méthode définit également la méthode de retour d'appel à utiliser. Cet appel doit être effectué après avoir sélectionné un classement avec
FindLeaderboard().
bool CSteamLeaderboards::DownloadScores()
{
if (!m_CurrentLeaderboard)
return false;
// charger les données du classement spécifié autour de l'utilisateur actuel
SteamAPICall_t hSteamAPICall = SteamUserStats()->DownloadLeaderboardEntries(
m_CurrentLeaderboard, k_ELeaderboardDataRequestGlobalAroundUser, -4, 5);
m_callResultDownloadScore.Set(hSteamAPICall, this,
&CSteamLeaderboards::OnDownloadScore);
return true;
}
OnDownloadScore()
Paramètres : sans objet
Éléments renvoyés : rien
Action : cette méthode est un rappel qui est appelé chaque fois que nous essayons de télécharger des entrées depuis un classement sur Steam. Si les données sont téléchargées avec succès, nous copions les données dans notre tableau d'entrées. Le nombre d'entrées téléchargées est stocké dans
m_nLeaderboardEntries.
void CSteamLeaderboards::OnDownloadScore(LeaderboardScoresDownloaded_t *pCallback, bool bIOFailure)
{
if (!bIOFailure)
{
m_nLeaderboardEntries = min(pCallback->m_cEntryCount, 10);
for (int index = 0; index < m_nLeaderboardEntries; index++)
{
SteamUserStats()->GetDownloadedLeaderboardEntry(
pCallback->m_hSteamLeaderboardEntries,index,&m_leaderboardEntries[index],NULL,0);
}
}
}
Étape 3 : intégration dans votre jeu
Voici une liste complète d'extraits de code que vous devez intégrer dans votre jeu aux emplacements appropriés.
Définitions et variables globales
Vous trouverez ci-dessous la liste des fichiers entête qui sont nécessaires pour construire avec l'objet classements et un pointeur global vers notre objet auxiliaire.
..
#include "steam_api.h"
#include "SteamLeaderboards.h"
//Accès global à l'objet classements
CSteamLeaderboards* g_SteamLeaderboards = NULL;
...
Initialisation
L'appel de
SteamAPI_Init initialise l'entièreté de Steam et doit être effectué avant toute autre chose. Si cet appel réussit, alors nous créons l'objet auxiliaire.
...
// Initialiser Steam
bool bRet = SteamAPI_Init();
// Créer l'objet SteamLeaderboards si Steam a été initialisé avec succès
if (bRet)
{
g_SteamLeaderboards = new CSteamLeaderboards();
}
...
Traitement des rappels
Pour nous assurer que nous traitons tous les rappels Steam, nous devons régulièrement faire remonter les nouveaux messages. Pour cela, il suffit d'ajouter cet appel dans la boucle du jeu.
...
SteamAPI_RunCallbacks();
...
Arrêt
L'appel de
SteamAPI_Shutdown se trouve probablement déjà dans votre code. Il arrête Steam et doit être appelé avant la fermeture de votre application. Enfin, nous supprimons l'objet auxiliaire que nous avons créé.
...
// Éteindre Steam
SteamAPI_Shutdown();
// Supprimer l'objet SteamLeaderboards
if (g_SteamLeaderboards)
delete g_SteamLeaderboards;
...
Étape 4 : test et dépannage
Cet échantillon de code fournit des informations de débogage à la console de débogage. Ces informations peuvent vous aider à comprendre quels appels réussissent ou échouent. Voici quelques messages d'échec typiques et leurs solutions :
L'application n'a pas réussi à démarrer, car steam_api.dll est introuvable. La réinstallation de l'application peut corriger ce problème.Assurez-vous que steam_api.dll est dans le même répertoire que l'exécutable.
[S_API FAIL] SteamAPI_Init() a échoué : impossible de trouver une instance de Steam en cours d'exécution ou un fichier steamclient.dll local.Vous n'avez probablement pas lancé le client Steam. Démarrez Steam et connectez-vous.
[S_API FAIL] SteamAPI_Init() a échoué : aucun AppID trouvé.Il est très probable que le fichier steam_appid.txt ne soit pas à l'emplacement attendu. Placez-le dans votre dossier source et assurez-vous qu'il contient votre numéro d'AppID.
