Einführung
Im Folgenden finden Sie eine kurze Schritt-für-Schritt-Anleitung, wie Sie einfache Steam-Bestenlisten in weniger als 10 Minuten in Ihre Anwendung integrieren können. Im Lieferumfang des
Steamworks SDKs ist eine große Beispielanwendung namens
Spacewar enthalten, welche die gesamte Bandbreite der Steam-Funktionen demonstriert und Ihre erste Anlaufstelle sein sollte, wenn Sie Funktionen in Aktion erleben möchten. Dieses Tutorial fasst die Informationen aus Spacewar und der Bestenlisten-API aus
ISteamUserStats auf die wesentlichen Informationen zusammen, die für Steam relevant sind.
Schritt 1 – Definieren der Bestenlisten für Ihr Spiel
Bestenlisten sind anwendungsspezifisch und werden auf der Seite zur
Bestenlisten-Konfiguration auf der Steamworks-Partnerseite eingerichtet.
Für die Definition einer Bestenliste müssen Sie die folgenden Felder ausfüllen:
- Name – Geben Sie einen aussagekräftigen Namen an, der intern in der Entwicklung verstanden wird.
- Communityname – Wenn die Bestenliste im Community-Hub angezeigt werden soll, geben Sie hier den öffentlichen Anzeigenamen ein. Wenn Sie keinen Namen eingeben, wird die Bestenliste nicht angezeigt.
- Sortiermethode – Geben Sie die Sortierreihenfolge für die Bestenliste an: aufsteigend, wenn der erste Eintrag die niedrigste Punktzahl sein soll, absteigend, wenn der erste Eintrag die höchste Punktzahl sein soll.
- Anzeigetyp – Legt fest, welche Arten von Daten in der Bestenliste angezeigt werden. Wählen Sie zwischen numerisch, Sekunden oder Millisekunden.
- Schreibt – Wenn dies auf 'trusted' gesetzt ist, können die Bestenlistenpunktzahlen nicht von Clients, sondern nur über die Web-API SetLeaderboardScore eingestellt werden. Die Standardeinstellung ist „false“.
- Liest – Wenn dies auf „Freunde“ gesetzt ist, darf das Spiel nur die Bestenliste der Freunde des Benutzers einsehen. Zum Lesen aller Punktzahlen braucht es die Web-API. Die Standardeinstellung ist „false“.
Schritt 2 – Kurzbeschreibung der Arbeit mit Bestenlisten
Der folgende Code ist spielübergreifend und kann entsprechend Ihrer Anforderungen in Ihr Spiel eingefügt werden. Die Klasse ist in dieser Form voll funktionsfähig, kann aber bei Bedarf problemlos erweitert werden. Der gesamte Code stammt direkt aus den Spacewar-Beispieldateien
Leaderboards.cpp/h.
Header-Datei
Als Nächstes definieren wir eine Helper-Klasse, die alle Aufrufe der Steam-Bestenlisten-API zusammenfasst und alle Steam-Aufrufergebnisse erstellt.
class CSteamLeaderboards
{
private:
SteamLeaderboard_t m_CurrentLeaderboard; // Handle to leaderboard
public:
int m_nLeaderboardEntries; // How many entries do we have?
LeaderboardEntry_t m_leaderboardEntries[10]; // The entries
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;
};
Codedatei
Konstruktor
Parameter – Keine
Rückgabewert – k. A.
Funktionsweise Funktionsweise: Dieser Konstruktor initialisiert lediglich die Instanzvariablen.
CSteamLeaderboards::CSteamLeaderboards() :
m_CurrentLeaderboard( NULL ),
m_nLeaderboardEntries( 0 )
{
}
FindLeaderboard()
Parameter – Der Bezeichnerstring der Bestenliste, die gesucht werden soll (z. B. „Zurückgelegte Distanz“).
Rückgabewert – entfällt
Funktionsweise – Diese Methode umschließt einen Aufruf von
ISteamUserStats::FindLeaderboard – einen asynchronen Aufruf an Steam, mit dem der Handle für eine bestimmten Bestenliste angefordert wird. Dieser Aufruf muss ausgeführt worden sein, bevor Sie Bestenlisteneinträge abrufen oder einstellen können. Mit dieser Methode legen Sie auch die zu verwendende Methode für die Aufrufrückgabe fest.
void CSteamLeaderboards::FindLeaderboard( const char *pchLeaderboardName )
{
m_CurrentLeaderboard = NULL;
SteamAPICall_t hSteamAPICall = SteamUserStats()->FindLeaderboard(pchLeaderboardName);
m_callResultFindLeaderboard.Set(hSteamAPICall, this,
&CSteamLeaderboards::OnFindLeaderboard);
}
OnFindLeaderboard()
Parameter – k. A.
Rückgabewert – entfällt
Funktionsweise Diese Methode ist ein Rückruf, die immer aufgerufen wird, wenn Sie eine Bestenliste auf Steam suchen. Wird die gesuchte Bestenliste gefunden, wird deren Handle zur aktuellen Bestenliste bestimmt.
void CSteamLeaderboards::OnFindLeaderboard( LeaderboardFindResult_t *pCallback, bool bIOFailure )
{
// Prüfen, ob wir während des Aufrufs auf einen Fehler gestoßen sind.
if ( !pCallback->m_bLeaderboardFound || bIOFailure )
{
OutputDebugString( "Leaderboard could not be found\n" );
return;
}
m_CurrentLeaderboard = pCallback->m_hSteamLeaderboard;
}
UploadScore()
Parameter – Ein int32 zur Angabe des Werts, der in der aktuellen Bestenliste gespeichert werden soll.
Rückgabewert – „false“, wenn noch keine Bestenliste ausgewählt wurde; andernfalls „true“.
Funktionsweise Diese Methode umschließt im Prinzip einen Aufruf von
ISteamUserStats::UploadLeaderboardScore – einen asynchronen Aufruf an Steam, mit dem die Punktzahl des aktuellen Benutzers in die ausgewählte Bestenliste hochgeladen wird. Mit dieser Methode legen Sie auch die zu verwendende Methode für die Aufrufrückgabe fest. Vor diesem Aufruf muss mit folgender Funktion eine Bestenliste ausgewählt worden sein:
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()
Parameter – k. A.
Rückgabewert – entfällt
Funktionsweise Diese Methode ist ein Rückruf, die immer aufgerufen wird, wenn Sie eine Punktzahl in eine Bestenliste auf Steam hochladen.
void CSteamLeaderboards::OnUploadScore(LeaderboardScoreUploaded_t *pCallback, bool bIOFailure)
{
if ( !pCallback->m_bSuccess || bIOFailure )
{
OutputDebugString( "Score could not be uploaded to Steam\n" );
}
}
DownloadScores()
Parameter – k. A.
Rückgabewert – „false“, wenn noch keine Bestenliste ausgewählt wurde; andernfalls „true“.
Funktionsweise – Diese Methode umschließt einen Aufruf von
ISteamUserStats::FindLeaderboard – einen asynchronen Aufruf an Steam, mit dem ein Satz Punktzahlen aus der ausgewählten Bestenliste heruntergeladen wird. In diesem Beispiel werden 10 Einträge heruntergeladen: 4 vor dem aktuellen Benutzer, der aktuelle Benutzer selbst und 5 nach dem aktuellen Benutzer. Sie können dies nach Belieben ändern, um beliebig viele Einträge aus beliebigen Ranglistenpositionen in der Bestenliste herunterzuladen. Mit dieser Methode legen Sie auch die zu verwendende Methode für die Aufrufrückgabe fest. Vor diesem Aufruf muss mit folgender Funktion eine Bestenliste ausgewählt worden sein:
FindLeaderboard().
bool CSteamLeaderboards::DownloadScores()
{
if (!m_CurrentLeaderboard)
return false;
// Laden der spezifischen Bestenlistendaten des aktuellen Nutzers.
SteamAPICall_t hSteamAPICall = SteamUserStats()->DownloadLeaderboardEntries(
m_CurrentLeaderboard, k_ELeaderboardDataRequestGlobalAroundUser, -4, 5);
m_callResultDownloadScore.Set(hSteamAPICall, this,
&CSteamLeaderboards::OnDownloadScore);
return true;
}
OnDownloadScore()
Parameter – k. A.
Rückgabewert – entfällt
Funktionsweise – Diese Methode ist ein Rückruf, die immer aufgerufen wird, wenn Sie Einträge aus einer Bestenliste auf Steam herunterladen. Erfolgreich heruntergeladene Daten werden in den Eintrag-Array kopiert. Die Anzahl der heruntergeladenen Einträge wird in
m_nLeaderboardEntries gespeichert.
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);
}
}
}
Schritt 3 – Integration in Ihr Spiel
Im Folgenden finden Sie eine vollständige Liste der Codeausschnitte, die Sie an den entsprechenden Stellen in Ihr Spiel integrieren müssen.
Definitionen und Globals
Im Folgenden finden Sie die Liste der Einschlüsse, die für die Erstellung von Bestenlisten erforderlich sind, und einen globalen Zeiger auf das Helper-Objekt.
...
#include "steam_api.h"
#include "SteamLeaderboards.h"
// Globaler Zugriff auf das Leaderboards-Objekt
CSteamLeaderboards* g_SteamLeaderboards = NULL;
...
Initialisierung
Der Aufruf von
SteamAPI_Init initialisiert Steam vollständig und muss vor allen anderen Schritten erfolgen. Wenn dieser Aufruf erfolgreich ist, wird das Helper-Objekt erstellt.
...
// Steam initialisieren
bool bRet = SteamAPI_Init();
// Erstellen eines SteamLeaderboards-Objekts, wenn Steam erfolgreich initialisiert wurde.
if (bRet)
{
g_SteamLeaderboards = new CSteamLeaderboards();
}
...
Verarbeiten von Rückrufe
Um sicherzustellen, dass alle Steam-Rückrufe verarbeitet werden, müssen wir regelmäßig auf neue Meldungen prüfen. Dies erreichen wir, indem wir der Spielschleife diesen Aufruf hinzufügen.
...
SteamAPI_RunCallbacks();
...
Beenden
Der Aufruf von
SteamAPI_Shutdown ist wahrscheinlich bereits in Ihrem Code enthalten. Dadurch wird Steam beendet. Dieser Aufruf muss erfolgen, bevor Ihre Anwendung beendet wird. Schließlich löschen wir das erstellte Helper-Objekt.
...
// Shutdown Steam
SteamAPI_Shutdown();
// Delete the SteamLeaderboards object
if (g_SteamLeaderboards)
delete g_SteamLeaderboards;
...
Schritt 4 – Testen und Problembehebung
Dieser Beispielcode gibt Debug-Informationen an die Debug-Konsole aus, anhand derer Sie erkennen können, welche Aufrufe erfolgreich sind und welche nicht. Im Folgenden finden Sie einige typische Fehlermeldungen und die zugehörigen Lösungen:
Diese Anwendung konnte nicht gestartet werden, da die steam_api.dll nicht gefunden wurde. Möglicherweise können Sie das Problem beheben, indem Sie die Anwendung neu installieren.Stellen Sie sicher, dass sich die steam_api.dll im selben Verzeichnis wie die ausführbare Datei befindet.
[S_API FAIL] SteamAPI_Init() fehlgeschlagen; keine ausgeführte Steam-Instanz oder keine lokale steamclient.dll gefunden.Höchstwahrscheinlich wird kein Steam-Client ausgeführt. Starten Sie Steam und melden Sie sich an.
[S_API FAIL] SteamAPI_Init() fehlgeschlagen; keine App-ID gefunden.Höchstwahrscheinlich ist die Datei steam_appid.txt nicht vorhanden. Legen Sie die Datei im Quellordner ab und stellen Sie sicher, dass sie Ihre App-ID enthält.
