Steamworks-dokumentaatio
Vaiheittaiset ohjeet: saavutukset
Lyhyesti
Käytä saavutuksia palkitaksesi pelaajia, jotka saavuttavat tietyn virstanpylvään pelissä tai jotka toimivat pelissä tietyllä tavalla.
Integraation taso
10 minuuttia ja alle 10 riviä koodia. Steamworks SDK-integrointi on välttämätön.

Johdanto

Saavutuksia voidaan käyttää tapana rohkaista ja palkita pelaajaa pelissä tehdyistä toimista tai saavutetuista virstanpylväistä. Niitä käytetään usein osoituksena tapoista, ajetuista kilometreistä, avatuista arkuista tai muista yleisistä pelissä tapahtuvista toiminnoista. Niitä voidaan käyttää myös auttamaan pelaajaa löytämään erilaisia tapoja pelata peliä. Kun saavutus on avattu, se näkyy pelaajaikkunan nurkassa ja pelaajan saavutussivulla.

Tekniset tiedot

Näillä ohjeilla voit integroida yksinkertaisia Steam-saavutuksia sovellukseesi alle kymmenessä minuutissa, alle kymmenellä koodikantaan tehdyllä koodirivillä. Steamworks SDK sisältää mainion Spacewar-esimerkkisovelluksen, jossa näet kaikki Steamin toiminnot. Tutustu siihen ensimmäisenä. Selkeyden vuoksi tähän ohjeeseen on tiivistetty vain tarpeelliset Spacewar-pelin sekä tilastojen ja saavutusten ohjelmointirajapintojen tiedot, joita tarvitaan Steam-tilastoja varten. Huomaa, että tilasto- ja saavutustiedoissa on paljon päällekkäisyyksiä. Jos integroit molemmat, monet kutsuista voi yhdistää.

Vaihe 1 – Pelisaavutusten määrittäminen

Saavutukset ovat sovelluskohtaisia, ja ne määritetään Saavutusten määrittäminen -sivulla Steamworks-sovellushallinnan palvelinpuolella. Tässä on Steamworksin Spacewar-esimerkkisovelluksen saavutuslista:

spacewar_achievement_examplescreenshot.jpg

Vaihe 2 – Saavutusten toiminta lyhyesti

Seuraava koodi on pelistä riippumaton, ja se voidaan lisätä peliin haluamallasi tavalla. Luokka on täysin toimiva sellaisenaan, mutta sen voi helposti muokata muita tarpeita varten. Koodi on otettu suoraan Spacewar-esimerkkitiedostoista: StatsAndAchievements.cpp/h.

Otsikkotiedosto

Määritämme ensin rakenteen Steamistä saadulle saavutuksen datalle ja tarjoamme makron sen tyyppisten objektien luomiselle. Nämä tiedot ovat suoraan yhteydessä Saavutusten määritys -sivun tietoihin.
#define _ACH_ID( id, name ) { id, #id, name, "", 0, 0 } struct Achievement_t { int m_eAchievementID; const char *m_pchAchievementID; char m_rgchName[128]; char m_rgchDescription[256]; bool m_bAchieved; int m_iIconImage; };

Seuraavaksi määritetään apuluokka, joka pakkaa kaikki Steam-tilastojen ohjelmointirajapintakutsut ja luo kaikki Steam-takaisinkutsut.
class CSteamAchievements { private: int64 m_iAppID; // Nykyinen AppID. Achievement_t *m_pAchievements; // Saavutusten tiedot. int m_iNumAchievements; // Saavutusten lukumäärä. bool m_bInitialized; // Olemmeko kutsuneet pyyntöjen tilastoja ja saaneet takaisinkutsun? public: CSteamAchievements(Achievement_t *Achievements, int NumAchievements); ~CSteamAchievements(); bool RequestStats(); bool SetAchievement(const char* ID); STEAM_CALLBACK( CSteamAchievements, OnUserStatsReceived, UserStatsReceived_t, m_CallbackUserStatsReceived ); STEAM_CALLBACK( CSteamAchievements, OnUserStatsStored, UserStatsStored_t, m_CallbackUserStatsStored ); STEAM_CALLBACK( CSteamAchievements, OnAchievementStored, UserAchievementStored_t, m_CallbackAchievementStored ); };

Kooditiedosto

Konstruktori

Parametrit – Konstruktori saa parametrinaan osoittimen saavutustaulukkoon sekä taulukon pituuden. Taulukon muotoilua käsitellään emopelin koodissa myöhemmin.
Paluuarvot
Toiminta – Konstruktori alustaa useita jäseniä ja poimii parhaillaan käyttämämme sovellustunnuksen (AppID). Lisäksi se kytkee takaisinkutsumetodit käsittelemään Steamiin tehtyjä asynkronisia kutsuja. Lopuksi konstruktori kutsuu RequestStats(), jolla se noutaa senhetkisen käyttäjän tilasto- ja saavutustiedot.
CSteamAchievements::CSteamAchievements(Achievement_t *Achievements, int NumAchievements): m_iAppID( 0 ), m_bInitialized( false ), m_CallbackUserStatsReceived( this, &CSteamAchievements::OnUserStatsReceived ), m_CallbackUserStatsStored( this, &CSteamAchievements::OnUserStatsStored ), m_CallbackAchievementStored( this, &CSteamAchievements::OnAchievementStored ) { m_iAppID = SteamUtils()->GetAppID(); m_pAchievements = Achievements; m_iNumAchievements = NumAchievements; RequestStats(); }

RequestStats()

Parametrit
Paluuarvot – Boolean-arvo, joka osoittaa, onnistuiko kutsu vai ei. Jos kutsu epäonnistui, Steamiä ei todennäköisesti ole alustettu. Varmista, että sinulla on Steam-asiakasohjelma auki, kun yrität suorittaa kutsun, ja sitä ennen on kutsuttu SteamAPI_Init.
Toiminta – Metodi paketoi Steamille lähetettävän asynkronisen ISteamUserStats::RequestCurrentStats-kutsun, jolla pyydetään nykyisen käyttäjän saavutuksia. Tämä kutsu on suoritettava, ennen kuin tilastoja tai saavutuksia voidaan määrittää. Metodin alustava kutsu tehdään konstruktorissa. Jos haluat tarkistaa päivitettyjä tilastoja tai saavutuksia, voit kutsua sitä aina uudelleen.
bool CSteamAchievements::RequestStats() { // Onko Steam ladattu? Jos ei, tilastoja ei voida hakea. if ( NULL == SteamUserStats() || NULL == SteamUser() ) { return false; } // Onko käyttäjä sisäänkirjautuneena? Jos ei, tilastoja ei voida hakea. if ( !SteamUser()->BLoggedOn() ) { return false; } // Pyynnön käyttäjätilastot. return SteamUserStats()->RequestCurrentStats(); }

SetAchievement()

Parametrit – Haettavan saavutuksen merkkijonon tunniste (esimerkiksi "ACH_WIN_ONE_GAME").
Paluuarvot – Boolean-arvo, joka osoittaa, onnistuiko kutsu vai ei. Jos kutsu epäonnistui, Steamiä ei ole alustettu tai et ole vielä käsitellyt alkuperäisen RequestStats-tilastopyynnön kutsun takaisinkutsua. Et voi määrittää saavutuksia ennen kuin takaisinkutsu on vastaanotettu.
Toiminta – Metodi määrittää saavutuksen saavutetuksi ja lähettää tuloksen Steamille. Voit määrittää saavutuksen useita kertoja, joten sinun ei tarvitse huolehtia siitä, että määrittäisit jo määritettyjä saavutuksia uudelleen. Tämä on asynkroninen kutsu, joka käynnistää kaksi takaisinkutsua: OnUserStatsStored() ja OnAchievementStored().
bool CSteamAchievements::SetAchievement(const char* ID) { // Olemmeko saaneet takaisinkutsua vielä Steamiltä? if (m_bInitialized) { SteamUserStats()->SetAchievement(ID); return SteamUserStats()->StoreStats(); } // Jos emme, saavutuksia ei voida vielä määrittää. return false; }

OnUserStatsReceived()

Parametrit
Paluuarvot – Ei mitään.
Toiminta – Tämä metodi on takaisinkutsu, jota kutsutaan aina, kun yrität pyytää tilastoja. Tilastoja ja saavutuksia pyydetään käyttämällä RequestStats(). Metodi päivittää m_pAchievements-jäsenmuuttujan vastaamaan viimeisimpiä Steamistä palautettuja tilasto- ja saavutustietoja.
void CSteamAchievements::OnUserStatsReceived( UserStatsReceived_t *pCallback ) { // Voimme saada muiden pelitilastojen takaisinkutsuja. Ohita ne! if ( m_iAppID == pCallback->m_nGameID ) { if ( k_EResultOK == pCallback->m_eResult ) { OutputDebugString("Received stats and achievements from Steam\n"); m_bInitialized = true; // Lataa saavutukset. for ( int iAch = 0; iAch { Achievement_t &ach = m_pAchievements[iAch]; SteamUserStats()->GetAchievement(ach.m_pchAchievementID, &ach.m_bAchieved); _snprintf( ach.m_rgchName, sizeof(ach.m_rgchName), "%s", SteamUserStats()->GetAchievementDisplayAttribute(ach.m_pchAchievementID, "name")); _snprintf( ach.m_rgchDescription, sizeof(ach.m_rgchDescription), "%s", SteamUserStats()->GetAchievementDisplayAttribute(ach.m_pchAchievementID, "desc")); } } else { char buffer[128]; _snprintf( buffer, 128, "RequestStats - failed, %d\n", pCallback->m_eResult ); OutputDebugString( buffer ); } } }

OnUserStatsStored()

Parametrit
Paluuarvot – Ei mitään.
Toiminta – Tämä metodi on takaisinkutsu, jota kutsutaan aina, kun yrität tallentaa tilastoja Steamiin.
void CSteamAchievements::OnUserStatsStored( UserStatsStored_t *pCallback ) { // Voimme saada muiden pelitilastojen takaisinkutsuja. Ohita ne. if ( m_iAppID == pCallback->m_nGameID ) { if ( k_EResultOK == pCallback->m_eResult ) { OutputDebugString( "Stored stats for Steam\n" ); } else { char buffer[128]; _snprintf( buffer, 128, "StatsStored - failed, %d\n", pCallback->m_eResult ); OutputDebugString( buffer ); } } }

OnAchievementStored()

Parametrit
Paluuarvot – Ei mitään.
Toiminta – Tämä metodi on takaisinkutsu, jota kutsutaan aina, kun saavutuksia tallennetaan onnistuneesti Steamiin.
void CSteamAchievements::OnAchievementStored( UserAchievementStored_t *pCallback ) { // Voimme saada muiden pelitilastojen takaisinkutsuja. Ohita ne. if ( m_iAppID == pCallback->m_nGameID ) { OutputDebugString( "Stored Achievement for Steam\n" ); } }

Vaihe 3 – Integrointi peliin

Seuraavassa on täydellinen lista koodipätkistä, jotka sinun tulisi integroida asianmukaisiin kohtiin pelissä.

Määritykset ja globaalit muuttujat

Tässä on lista sisällytettävistä tiedoista, joita tarvitaan saavutusten, pelikohtaisen tilastotaulukon, pelikohtaisten saavutusten lueteltujen tyyppien sekä avustajaobjektin yleisosoittimen tekemiseen. Huomaa, että saavutukset vastaavat Steamworksin hallintasivun vastaavia.
... #include "steam_api.h" // Määrittelee saavutuksemme. enum EAchievements { ACH_WIN_ONE_GAME = 0, ACH_WIN_100_GAMES = 1, ACH_TRAVEL_FAR_ACCUM = 2, ACH_TRAVEL_FAR_SINGLE = 3, }; // Saavutustaulukko, joka säilyttää tiedot saavutuksista ja niiden tilasta. Achievement_t g_Achievements[] = { _ACH_ID( ACH_WIN_ONE_GAME, "Winner" ), _ACH_ID( ACH_WIN_100_GAMES, "Champion" ), _ACH_ID( ACH_TRAVEL_FAR_ACCUM, "Interstellar" ), _ACH_ID( ACH_TRAVEL_FAR_SINGLE, "Orbiter" ), }; // Saavutusobjektien yleiskäyttöoikeus. CSteamAchievements* g_SteamAchievements = NULL; ...

Alustaminen

Koko Steam alustetaan kutsumalla SteamAPI_Init. Sitä on kutsuttava ennen muita. Jos tämä kutsu onnistuu, luomme apuobjektin antamalla sille saavutustaulukon ja sen koon.
... // Alusta Steam. bool bRet = SteamAPI_Init(); // Luo SteamAchievements-objekti, jos Steamin alustus onnistui. if (bRet) { g_SteamAchievements = new CSteamAchievements(g_Achievements, 4); } ...

Takaisinkutsujen käsitteleminen

Jotta voimme varmistua, että kaikki Steam-takaisinkutsut tulevat käsitellyiksi, uusia viestejä on haettava säännöllisesti. Se tehdään lisäämällä tämä kutsu pelisilmukkaan.
... SteamAPI_RunCallbacks();

Saavutusten käynnistäminen

Saavutuksen käynnistäminen on niinkin yksinkertaista kuin saavutuksen tunnisteen välittäminen yhdessä kutsussa.
... if (g_SteamAchievements) g_SteamAchievements->SetAchievement("ACH_WIN_100_GAMES"); ...

Sammutus

Koodisi sisältää todennäköisesti jo SteamAPI_Shutdown-funktion kutsun. Se sammuttaa Steamin, joten sitä on kutsuttava ennen sovelluksen sulkeutumista. Lopuksi poistetaan aiemmin luotu aputoiminto-objekti.
... // Sulje Steam SteamAPI_Shutdown(); // Poista SteamAchievements-objekti. if (g_SteamAchievements) delete g_SteamAchievements; ...

Vaihe 4 – Testaus ja vianmääritys


Voit asettaa tai tyhjentää tilastoja tai saavutuksen lisäämättä koodia peliisi käyttämällä Steam-asiakasohjelman konsolia. Suorita steam.exe-konsolilla ja sen jälkeen:
  • achievement_clear
  • reset_all_stats