Steamworks-dokumentaatio
Vaiheittaiset ohjeet: tilastot

Johdanto

Näillä ohjeilla voit integroida Steamin perustilastoja sovellukseesi alle kymmenessä minuutissa ja vähmmällä kuin kymmenellä koodirivillä tietokantaasi. Steamworks-sovelluskehityspaketissa on mainio Spacewar-esimerkkisovellus, joka esittelee Steam-toiminnot koko laajuudessaan. Steamin toimintojen tarkastelu kannattaa aloittaa käytännössä esimerkkisovelluksesta. Selkeyden vuoksi tähän ohjeeseen on tiivistetty tarpeelliset Spacewar-, tilasto- ja saavutusten ohjelmointirajapintatiedot, joita tarvitaan Steam-tilastoissa. Huomaa, että tilasto- ja saavutustiedoissa on paljon päällekkäistä informaatiota. Jos integroit kummatkin, huomaa, että monet kutsuista voi yhdistää.

Vaihe 1 – Pelitilastojen määrittäminen

Tilastot ovat sovelluskohtaisia, ja ne määritetään Tilastojen määrittäminen -sivulla Steamworks-sovellushallinnan taustajärjestelmässä. Alla on luettelo Steamworksin Spacewar-esimerkkipelin tilastoista:
:
stats_spacewar.png

Vaihe 2 – Tilastojen toiminta lyhyesti

Seuraavan koodin voit lisätä peliin haluamallasi tavalla, koska se on pelistä riippumatonta. Luokka on täysin toimiva sellaisenaan, mutta sen voi helposti muokata muita tarpeita varten. Koodi on otettu suoraan Spacewar-esimerkkitiedostoista: StatsAndAchievements.cpp/h.

Otsikkotiedosto

Aluksi määritämme rakenteen, jolla säilytämme Steamista haetut tilastotiedot. Määritä tilastotyypit näppärästi enum-muuttujina ja tuo makro tilastokohteiden luomiseksi. Nämä tiedot ovat suoraan yhteydessä Tilastojen määritys -sivun tietoihin.
#define _STAT_ID( id,type,name ) { id, type, name, 0, 0, 0, 0 } enum EStatTypes { STAT_INT = 0, STAT_FLOAT = 1, STAT_AVGRATE = 2, }; struct Stat_t { int m_ID; EStatTypes m_eStatType; const char *m_pchStatName; int m_iValue; float m_flValue; float m_flAvgNumerator; float m_flAvgDenominator; };

Seuraavaksi määritetään apuluokka, joka pakkaa kaikki Steam-tilastojen ohjelmointirajapintakutsut ja luo kaikki Steam-takaisinkutsut.
class CSteamStats { private: int64 m_iAppID; // Nykyiden sovell AppID: mme Stat_t *m_pStats; // Tilastotiedot int m_iNumStats; // Tilastojen lukumäärä bool m_bInitialized; // Olemmeko tehneet Request stats -kutsun ja saaneet takaisinkutsun? public: CSteamStats(Stat_t *Stats, int NumStats); ~CSteamStats(); bool RequestStats(); bool StoreStats(); STEAM_CALLBACK( CSteamStats, OnUserStatsReceived, UserStatsReceived_t, m_CallbackUserStatsReceived ); STEAM_CALLBACK( CSteamStats, OnUserStatsStored, UserStatsStored_t, m_CallbackUserStatsStored ); };

Kooditiedosto

Konstruktori

Muuttujat – Konstruktori tuo osoittajan tilastojen jonoon sen pituuden mukaisesti. Pääpelin koodin kohdalla käsitellään myöhemmin jonon muotoilua.
Palautukset - Ei käytössä.
Toiminta – Konstruktori alustaa useita jäseniä ja kaappaa tällä hetkellä käyttämämme sovellustunnuksen. Lisäksi se kytkee takaisinkutsumenetelmät käsittelemään Steamiin tehtyjä asynkronisia kutsuja. Se suorittaa lopuksi ensimmäisen RequestStats()-kutsun, jolla se noutaa senhetkisen käyttäjän tilasto- ja saavutustiedot.
CSteamStats::CSteamStats(Stat_t *Stats, int NumStats) : m_iAppID( 0 ), m_bInitialized( false ), m_CallbackUserStatsReceived( this, &CSteamStats::OnUserStatsReceived ), m_CallbackUserStatsStored( this, &CSteamStats::OnUserStatsStored ) { m_iAppID = SteamUtils()->GetAppID(); m_pStats = Stats; m_iNumStats = NumStats; RequestStats(); }

RequestStats()

Muuttujat – Ei ole
Palautukset – Boolean muuttuja, joka edustaa sitä, oliko kutsu tosi vai epätosi, eli onnistuiko se. Steamiä ei ole todennäköisesti alustettu, jos kutsu epäonnistui. Varmista, että sinulla on Steam-sovellus päällä, kun yrität suorittaa kutsun; ja sitä ennen on suoritettu SteamAPI_Init-kutsu.
Toiminta – Tämä menetelmä paketoi Steamille lähetettävän asynkronisen ISteamUserStats::RequestCurrentStats-kutsun, jolla pyydetään nykyisen käyttäjän tilastoja. Tämä kutsu on suoritettava, ennen kuin tilastoja tai saavutuksia voidaan määrittää. Konstruktorissa tehdään menetelmän alustava kutsu. Voit kutsua sitä myöhemmin uudelleen, jos haluat tarkistaa päivitettyjä tilastoja tai saavutuksia.
bool CSteamStats::RequestStats() { // Onko Steam ladattu? Jos ei, emme voi hakea tilastoja. if ( NULL == SteamUserStats() || NULL == SteamUser() ) { return false; } // Onko käyttäjä kirjautuneena? Jos ei, emme voi hakea tilastoja. if ( !SteamUser()->BLoggedOn() ) { return false; } // Pyydä käyttäjätilastoja. return SteamUserStats()->RequestCurrentStats(); }

StoreStats()

Muuttujat – Ei ole
Palautukset – Boolean muuttuja, joka osoittaa, onnistuiko kutsu vai ei. Jos kutsu epäonnistui, Steamia ei todennäköisesti ole alustettu. Varmista, että Steam-sovellus on auki, kun yrität suorittaa kutsun; ja sitä ennen on suoritettu SteamAPI_Init-kutsu.
Toiminta – Tässä menetelmässä käytännössä paketoidaan ISteamUserStats::StoreStats-kutsu, joka on Steamille lähetettävä asynkroninen kutsu, jolla tallennetaan nykyisen käyttäjän tilastot palvelimelle. Kutsu tulee tehdä aina, kun haluat päivittää käyttäjän tilastot.
bool CSteamStats::StoreStats() { if ( m_bInitialized ) { // lataa tilastot for ( int iStat = 0; iStat < m_NumStats; ++iStat ) { Stat_t &stat = m_pStats[iStat]; switch (stat.m_eStatType) { case STAT_INT: SteamUserStats()->SetStat( stat.m_pchStatName, stat.m_iValue ); break; case STAT_FLOAT: SteamUserStats()->SetStat( stat.m_pchStatName, stat.m_flValue ); break; case STAT_AVGRATE: SteamUserStats()->UpdateAvgRateStat(stat.m_pchStatName, stat.m_flAvgNumerator, stat.m_flAvgDenominator ); // Keskiarvotulos on laskettu meille. SteamUserStats()->GetStat(stat.m_pchStatName, &stat.m_flValue ); break; default: break; } } return SteamUserStats()->StoreStats(); } }

OnUserStatsReceived()

Muuttajat - Ei käytössä.
Palautukset – Ei ole.
Toiminta – Menetelmä on takaisinkutsu, jota kutsutaan aina, kun yrität pyytää tilastoja. Tilastoja pyydetään käyttämällä kutsua RequestStats(). Menetelmä päivittää m_Stats-jäsenmuuttujan vastaamaan viimeisimpiä tilastotietoja, jotka on palautettu Steamistä.
void CSteamStats::OnUserStatsReceived( UserStatsReceived_t *pCallback ) { // Voimme saada muiden pelien saapuvilta tilastoilta takaisinkutsuja. Hylkää ne. if ( m_iAppID == pCallback->m_nGameID ) { if ( k_EResultOK == pCallback->m_eResult ) { OutputDebugString( "Received stats and achievements from Steam\n" ); // lataa tilastot for ( int iStat = 0; iStat < m_iNumStats; ++iStat ) { Stat_t &stat = m_Stats[iStat]; switch (stat.m_eStatType) { case STAT_INT: SteamUserStats()->GetStat(stat.m_pchStatName, &stat.m_iValue); break; case STAT_FLOAT: case STAT_AVGRATE: SteamUserStats()->GetStat(stat.m_pchStatName, &stat.m_flValue); break; default: break; } } m_bInitialized = true; } else { char buffer[128]; _snprintf( buffer, 128, "RequestStats - failed, %d\n", pCallback->m_eResult ); OutputDebugString( buffer ); } } }

OnUserStatsStored()

Muuttujat - Ei käytössä.
Palautukset – Ei ole.
Toiminta – Tämä menetelmä on vastakutsu, jota kutsutaan aina, kun yrität tallentaa tilastoja Steamiin. Jos jotkin tilastoista, jotka yritimme määrittää, rikkoivat rajoitetta, ne palautetaan vanhaan arvoon, joten lataamme niiden arvot uudelleen.
void CSteamStats::OnUserStatsStored( UserStatsStored_t *pCallback ) { // Voimme saada muiden pelien tilastojen takaisinkutsuja. Ohita ne. if ( m_iAppID == pCallback->m_nGameID ) { if ( k_EResultOK == pCallback->m_eResult ) { OutputDebugString( "StoreStats - success\n" ); } else if ( k_EResultInvalidParam == pCallback->m_eResult ) { // Yksi tai useampi määrittämistämme tilastoista rikkoi rajoitteen. Ne on palautettu, // ja meidän tulisi iteroida arvot uudelleen , jotta pysymme tahdistuksessa. OutputDebugString( "StoreStats - some failed to validate\n" ); // Feikkaa takaisinkutsu tässä, jotta voimme ladata arvot uudestaan. UserStatsReceived_t callback; callback.m_eResult = k_EResultOK; callback.m_nGameID = m_iAppID; OnUserStatsReceived( &callback ); } else { char buffer[128]; _snprintf( buffer, 128, "StoreStats - failed, %d\n", pCallback->m_eResult ); OutputDebugString( buffer ); } } }

Vaihe 3 – Integrointi peliisi

Seuraavassa on täydellinen luettelo koodipätkistä, jotka sinun tulisi integroida oikeisiin kohtiin pelissäsi.

Muuttujat ja yleismuuttujat

Seuraavassa on luettelo sisällytyksistä, joita tarvitaan pelikohtaisen Stats-jonon, yleisosoittimen ja apuohjelmamme rakentamiseen. Huomaa, että tilastot vastaavat Steamworksin hallintasivun vastaavia.
... #include "steam_api.h" #include "isteamuserstats.h" #include "SteamStats.h" // Tilastotaulukko, joka säilyttää tilastotiedot ja niiden tilan. Stat_t g_Stats[] = { _STAT_ID( 1, STAT_INT, "NumGames"), _STAT_ID( 2, STAT_INT, "NumWins"), _STAT_ID( 3, STAT_INT, "NumLosses"), _STAT_ID( 4, STAT_FLOAT, "FeetTraveled"), _STAT_ID( 5, STAT_AVGRATE, "AverageSpeed"), _STAT_ID( 7, STAT_FLOAT, "MaxFeetTraveled"), }; // Yleisoikeudet tilastokohteeseen CSteamStats* g_SteamStats = NULL; ...

Alustus

Koko Steam alustetaan SteamAPI_Init-kutsulla. Sitä on kutsuttava ensiksi. Jos tämä kutsu onnistuu, luomme apuobjektin antamalla sille tilastotaulukon ja sen koon.
... // Alusta Steam. bool bRet = SteamAPI_Init(); // Luo SteamStats-objektit, jos Steamin alustus onnistui. if (bRet) { g_SteamStats = new CSteamStats(g_Stats, 6); } ...

Takaisinkutsujen käsittely

Meidän on säännöllisesti noudettava uusia viestejä, jotta varmistamme sen, että käsittelemme kaikki Steamin takaisinkutsut. Tämä saavutetaan lisäämällä this-kutsu pelisilmukkaan.
... SteamAPI_RunCallbacks(); ...

Tilastojen tallentaminen

Tilastot tallennetaan suorittamalla yksittäinen StoreStats()-kutsu.
... if (g_SteamStats) g_SteamStats->StoreStats(); ...

Sammutus

Koodisi sisältää todennäköisesti jo SteamAPI_Shutdown-kutsun. Se sammuttaa Steamin. Koodia on kutsuttava ennen sovelluksen lopettamista. Lopuksi poistamme luomamme apuobjektin.
... // Sulje Steam SteamAPI_Shutdown(); // Poista SteamStats-objekti if (g_SteamStats) delete g_SteamStats; ...

Vaihe 4 – Testaus ja vianmääritys

Tämä esimerkkikoodi tulostaa virheenkorjaustiedot näkymäksi, joka voi auttaa ymmärtämään, mitkä kutsuista onnistuvat ja mitkä epäonnistuvat. Seuraavat ovat tyypillisiä virhilmoituksia ja niiden korjausehdotuksia.

Tämän sovelluksen käynnistyminen epäonnistui, koska steam_api.dll-tiedostoa ei löytynyt. Sovelluksen uudelleenkäynnistäminen voi korjata ongelman.
Varmista, että steam_api.dll-tiedosto on ohjelmatiedoston kanssa samassa hakemistossa.

[S_API FAIL] SteamAPI_Init() epäonnistui. Steamin päällä olevaa tapausta tai paikallista steamclient.dll-tiedostoa ei löytynyt
Sinulla ei todennäköisesti ole Steam-sovellus päällä. Käynnistä Steam ja kirjaudu sisään.

[S_API FAIL] SteamAPI_Init() epäonnistui. Sovellustunnusta ei löytynyt.
Sinulla ei todennäköisesti ole steam_appid.txt-tiedostoa tarvittavassa paikassa. Lisää se lähdekansioon ja varmista, että siinä on sovellustunnusnumerosi.