Bevezetés
Az alábbiak egy gyors, lépésről lépésre útmutatót tartalmaznak egy nagyon alapszintű Steam ranglista integrálásához az alkalmazásodba, kevesebb mint tíz perc alatt. A
Steamworks SDK tartalmaz egy nagyszerű,
Spacewar nevű példaalkalmazást, amely bemutatja a Steam szolgáltatások teljes skáláját, és érdemes ezzel kezdeni, hogy lásd az összes Steam funkciót működés közben. Ez az oktatás leszűkíti a Spacewarban és az
ISteamUserStats-ban található Ranglisták API információkat a csak a Steam Ranglistákhoz szükségesekre, hogy a dolgok a lehető legegyszerűbbek legyenek.
1. lépés – A játékod ranglistáinak meghatározása
A ranglisták alkalmazásspecifikusak, és a Steamworks alkalmazás-adminisztrációs háttérrendszer
Ranglista-beállítások oldalán állíthatók be.
Ranglista definiálásához a következő mezőket kell kitölteni:
- Név – Állítsd be ezt a nevet arra, ami a belső fejlesztés részeként észszerű.
- Közösségi név – Ha a ranglistát meg kell jeleníteni a közösségközpontban, itt állítsd be a nyilvános nevet. Ha nincs név megadva, a ranglista nem jelenik meg.
- Rendezési mód – Állítsd be a ranglista rendezési sorrendjét. Helyezéses ranglistákhoz használd az Emelkedőt. Pontszámokhoz a Csökkenőt.
- Megjelenítés típusa – A ranglistán megjelenítendő adattípust határozza meg. Numerikus, Másodperc és Ezredmásodperc lehetőségből választhatsz.
- Írás – Ha ez Megbízhatóra van állítva, a ranglista pontszámait a kliensek nem tudják beállítani, és azok csak a SetLeaderboardScore WebAPI-n keresztül állíthatók. Az alapértéke false.
- Olvasás – Ha ez Barátokra van állítva, a játék csak a felhasználó barátainak ranglistáját tudja olvasni; webes API-val mindig minden pontszám beolvasható. Az alapértéke false.
2. lépés – A ranglista-beágyazási munka
Az alábbi kód játékfüggetlen, és tetszés szerint hozzáadható a játékodhoz. Az osztály jelen állapotában is teljesen működőképes, de könnyen bővíthető bármilyen további igény kielégítésére. Ezt a kódot közvetlenül a Spacewar példafájljaiból vettük:
Leaderboards.cpp/h.
Fejléc fájl
Definiálunk egy segítő osztályt, amely becsomagolja az összes Steam Ranglisták API-hívást, valamint létrehozza az összes Steam hívási eredménykezelőt.
class CSteamLeaderboards
{
private:
SteamLeaderboard_t m_CurrentLeaderboard; // A ranglistára mutató leíró.
public:
int m_nLeaderboardEntries; // Hány bejegyzésünk van?
LeaderboardEntry_t m_leaderboardEntries[10]; // A bejegyzések.
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;
};
Kódfájl
Konstruktor
Paraméterek: nincs.
Visszatérési érték: nincs.
Mit csinál: ez a konstruktor csak inicializálja a tagváltozókat.
CSteamLeaderboards::CSteamLeaderboards() :
m_CurrentLeaderboard( NULL ),
m_nLeaderboardEntries( 0 )
{
}
FindLeaderboard()
Paraméterek: A megtalálni kívánt ranglista karakterlánc-azonosítója (pl. „Megtett távolság”).
Visszatérési érték: semmi.
Mit csinál: Ez a metódus becsomagol egy
ISteamUserStats::FindLeaderboard hívást, amely egy aszinkron hívás a Steamhez a kérdéses ranglistára mutató leíró lekérésére. Ezt a hívást végre kell hajtani, mielőtt ranglista-bejegyzéseket tudnál lekérni vagy beállítani. A metódus előkészíti a használandó hívásvisszatérési metódust is.
void CSteamLeaderboards::FindLeaderboard( const char *pchLeaderboardName )
{
m_CurrentLeaderboard = NULL;
SteamAPICall_t hSteamAPICall = SteamUserStats()->FindLeaderboard(pchLeaderboardName);
m_callResultFindLeaderboard.Set(hSteamAPICall, this,
&CSteamLeaderboards::OnFindLeaderboard);
}
OnFindLeaderboard()
Paraméterek: nincs.
Visszatérési érték: semmi.
Mit csinál: Ez a metódus egy callback, amely meghívódik, valahányszor ranglistát próbálsz keresni a Steamen. Ha a kért ranglista megtalálható, akkor beállítjuk annak leíróját az aktuális ranglistánkként.
void CSteamLeaderboards::OnFindLeaderboard( LeaderboardFindResult_t *pCallback, bool bIOFailure )
{
// megnézzük, ütköztünk-e hibába a hívás során
if ( !pCallback->m_bLeaderboardFound || bIOFailure )
{
OutputDebugString( "A ranglista nem található.\n" );
return;
}
m_CurrentLeaderboard = pCallback->m_hSteamLeaderboard;
}
UploadScore()
Paraméterek: egy int32, amely az aktuális ranglistában tárolandó értéket képviseli.
Visszatérési érték: „false”, ha még nincs kiválasztva ranglista, egyéb esetben „true” értéket ad vissza.
Mit csinál: Ez a metódus becsomagol egy
ISteamUserStats::UploadLeaderboard hívást, amely egy aszinkron hívás a Steamhez, ami feltölti a jelenlegi felhasználó pontszámát a jelenleg kiválasztott ranglistába. A metódus előkészíti a használandó hívásvisszatérési metódust is. Ezt a hívást az után kell elvégezni, hogy a
FindLeaderboard() használatával kiválasztottál egy ranglistát.
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éterek: nincs.
Visszatérési érték: semmi.
Mit csinál: Ez a metódus egy callback, amely meghívódik, valahányszor pontszámot próbálsz feltölteni egy ranglistára a Steamen.
void CSteamLeaderboards::OnUploadScore(LeaderboardScoreUploaded_t *pCallback, bool bIOFailure)
{
if ( !pCallback->m_bSuccess || bIOFailure )
{
OutputDebugString( "A pontszámot nem lehetett feltölteni a Steamre.\n" );
}
}
DownloadScores()
Paraméterek: nincs.
Visszatérési érték: „false”, ha még nincs kiválasztva ranglista, egyéb esetben „true” értéket ad vissza.
Mit csinál: Ez a metódus becsomagol egy
ISteamUserStats::DownloadLeaderboardEntries hívást, amely egy aszinkron hívás a Steamhez, ami letölt egy sor bejegyzést a jelenleg kiválasztott ranglistából. Ebben az esetben tíz bejegyzést töltünk le, négyet az aktuális felhasználó előtt, az aktuális felhasználót és ötöt az aktuális felhasználó után. Ez a hívás megváltoztatható bármennyi bejegyzés visszaadására, bármelyik helyről a ranglistán. A metódus előkészíti a használandó hívásvisszatérési metódust is. Ezt a hívást az után kell elvégezni, hogy a
FindLeaderboard() használatával kiválasztottál egy ranglistát.
bool CSteamLeaderboards::DownloadScores()
{
if (!m_CurrentLeaderboard)
return false;
// a meghatározott ranglistaadatok betöltése a jelenlegi felhasználó körül
SteamAPICall_t hSteamAPICall = SteamUserStats()->DownloadLeaderboardEntries(
m_CurrentLeaderboard, k_ELeaderboardDataRequestGlobalAroundUser, -4, 5);
m_callResultDownloadScore.Set(hSteamAPICall, this,
&CSteamLeaderboards::OnDownloadScore);
return true;
}
OnDownloadScore()
Paraméterek: nincs.
Visszatérési érték: semmi.
Mit csinál: Ez a metódus egy callback, amely meghívódik, valahányszor bejegyzéseket próbálsz letölteni egy ranglistáról a Steamen. Ha az adat sikeresen letöltődött, akkor bejegyzéstömbünkbe másoljuk azt. A letöltött bejegyzések számát az
m_nLeaderboardEntries tárolja.
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);
}
}
}
3. lépés – Integrálás a játékodba
Az alábbi mindazon kódrészletek felsorolása, amelyeket a megfelelő helyeken integrálnod kell a játékba.
Defines és Globals
Az alábbi azon include-ok listája, amelyek szükségesek a Ranglistákkal végzett buildhez, és egy, a helper objektumunkra mutató globális mutató.
...
#include "steam_api.h"
#include "SteamLeaderboards.h"
// Globális hozzáférés a Leaderboards objektumhoz
CSteamLeaderboards* g_SteamLeaderboards = NULL;
...
Inicializálás
Az
SteamAPI_Init meghívása inicializálja a teljes Steamet, és minden más előtt kell meghívni. Ha ez a hívás sikeres, létrehozzuk a helper objektumot.
...
// Steam inicializálása
bool bRet = SteamAPI_Init();
// A SteamLeaderboards objektum létrehozása, ha a Steam inicializálása sikeres volt
if (bRet)
{
g_SteamLeaderboards = new CSteamLeaderboards();
}
...
Callbackek feldolgozása
Az összes Steam callback feldolgozásának biztosítására rendszeresen keresnünk kell az új üzeneteket. Ezt az alábbinak a játékhurokhoz adásával érjük el:.
...
SteamAPI_RunCallbacks();
...
Leállítás
A
SteamAPI_Shutdown meghívása már valószínűleg szerepel a kódodban. Ez állítja le a Steamet, és az alkalmazásod kilépése előtt meg kell hívni. Végül töröljük az általunk létrehozott helper objektumot.
...
// Steam leállítása
SteamAPI_Shutdown();
// A SteamLeaderboards objektum törlése
if (g_SteamLeaderboards)
delete g_SteamLeaderboards;
...
4. lépés – Tesztelés és hibaelhárítás
Ez a mintakód hibakeresési információkat ad ki a hibakereső konzolra, amelyek segíthetnek megérteni, mely hívások sikeresek vagy sikertelenek. Alább látható néhány jellegzetes hibaüzenet és javításuk:
This application has failed to start because steam_api.dll was not found. Az alkalmazás újratelepítése megoldhatja ezt a problémát.Győződj meg róla, hogy a steam_api.dll ugyanabban a könyvtárban van, mint a végrehajtható fájl.
[S_API FAIL] SteamAPI_Init() failed; unable to locate a running instance of Steam, or a local steamclient.dllValószínűleg nem fut Steam kliens. Indítsd el a Steamet, és jelentkezz be.
[S_API FAIL] SteamAPI_Init() failed; no appID found.Valószínűleg nincs a helyén a steam_appid.txt fájl. Helyezd el a forrásmappába, és győződj meg róla, hogy benne van az AppID számod.
