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:
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 < m_iNumAchievements; ++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 <appid> <achievement name>
- reset_all_stats <appid>
