Johdanto
Näillä pikaohjeilla voit integroida sovellukseesi Steamin peruspistetaulukoita alle kymmenessä minuutissa.
Steamworks-sovelluskehityspaketti sisältää hienon
Spacewar-esimerkkisovelluksen, jossa näet kaikki Steamin toiminnot. Tutustu siihen ensimmäisenä. Selkeyden vuoksi tähän ohjeeseen on tiivistetty Spacewar-pelistä ja pistetaulukkojen ohjelmointirajapinnasta
ISteamUserStats-käyttöliittymällä saadut, Steamin pistetaulukoihin vaadittavat tiedot.
Vaihe 1 – Pelin pistetaulukkojen määrittäminen
Pistetaulukot ovat sovelluskohtaisia, ja ne määritetään Steamworks-kumppanisivuston
Pistetaulukkojen määrittäminen -sivulla.
Pistetaulukon määrittäminen edellyttää seuraavien kenttien täyttämistä:
- Nimi: valitse sisäisen kehityksen kannalta looginen nimi.
- Yhteisönimi: jos pistetaulukko näytetään yhteisökeskuksessa, valitse tähän julkisesti näkyvä nimi. Jos nimeä ei anneta, pistetaulukkoa ei näytetä.
- Lajittelutapa: määritä pistetaulukon lajittelujärjestys. Valitse "Nouseva", jos taulukko perustuu sijoitukseen. Valitse "Laskeva", jos taulukko perustuu pistemäärään.
- Näyttötapa: määrittää pistetaulukossa näytettävien tietojen tyypit. Vaihtoehtoina ovat numeerinen, sekunnit ja millisekunnit.
- Kirjoittaa: Jos arvoksi asetetaan "Luotettu", asiakasohjelmat eivät voi määrittää pistetaulukon tuloksia. Tuolloin ne voidaan ainoastaan määrittää SetLeaderboardScore-verkko-ohjelmointirajapinnan kautta. Oletusarvona on "false" (epätosi).
- Lukee: Peli voi ainoastaan lukea käyttäjän kavereiden pistetaulukkotuloksia, jos arvoksi on määritetty "Kaverit". Verkko-ohjelmointirajapinta voi aina lukea kaikki tulokset. Oletusarvona on "false" (epätosi).
Vaihe 2 – Pistetaulukon toiminnan kapselointi
Seuraavan koodin voit lisätä peliin haluamallasi tavalla, koska se on pelistä riippumaton. Luokka on täysin toimiva sellaisenaan, mutta sen voi helposti muokata muita tarpeita varten. Koko koodi on otettu suoraan Spacewarin esimerkkitiedostoista:
Leaderboards.cpp/h.
Otsikkotiedosto
Määritetään aputoimintoluokka, joka paketoi kaikki Steamin pistetaulukon ohjelmointirajapintakutsut ja luo kaikki Steam-kutsutulosten käsittelijät.
class CSteamLeaderboards
{
private:
SteamLeaderboard_t m_CurrentLeaderboard; // Käsittele pistetaulukossa.
public:
int m_nLeaderboardEntries; // Kuinka monta merkintää on?
LeaderboardEntry_t m_leaderboardEntries[10]; // Merkinnät
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;
};
Kooditiedosto
Konstruktori
Parametrit: –
Paluuarvot: –
Tehtävä: Konstruktori vain alustaa jäsenmuuttujat.
CSteamLeaderboards::CSteamLeaderboards() :
m_CurrentLeaderboard( NULL ),
m_nLeaderboardEntries( 0 )
{
}
FindLeaderboard()
Parametrit Haettavan pistetaulukon merkkijonon tunniste (esimerkiksi ”Kuljettu matka”)
Paluuarvot: –
Tehtävä: Metodi paketoi kutsun jäsenfunktioon
ISteamUserStats::FindLeaderboard. Kyseessä on Steamille lähetettävä asynkroninen kutsu, joka pyytää kahvaa pistetaulukolle. Kutsu on tehtävä, ennen kuin voit palauttaa tai asettaa pistetaulukkomerkintöjä. Metodi määrittää myös käytettävän kutsun palautusmetodin.
void CSteamLeaderboards::FindLeaderboard( const char *pchLeaderboardName )
{
m_CurrentLeaderboard = NULL;
SteamAPICall_t hSteamAPICall = SteamUserStats()->FindLeaderboard(pchLeaderboardName);
m_callResultFindLeaderboard.Set(hSteamAPICall, this,
&CSteamLeaderboards::OnFindLeaderboard);
}
OnFindLeaderboard()
Parametrit: –
Paluuarvot: –
Tehtävä: Metodi on takaisinkutsu, jota kutsutaan aina, kun yritetään löytää pistetaulukkoa Steamissä. Jos pyydetty pistetaulukko löytyi, kyseisen pistetaulukon nimi asetetaan nykyiseksi pistetaulukoksi.
void CSteamLeaderboards::OnFindLeaderboard( LeaderboardFindResult_t *pCallback, bool bIOFailure )
{
// Katso, oliko meillä virhettä kutsun aikana.
if ( !pCallback->m_bLeaderboardFound || bIOFailure )
{
OutputDebugString( "Leaderboard could not be found\n" );
return;
}
m_CurrentLeaderboard = pCallback->m_hSteamLeaderboard;
}
UploadScore()
Parametrit: Int32-muuttuja edustaa nykyiseen pistetaulukkoon tallennettavaa arvoa.
Paluuarvot: False, jos pistetaulukkoa ei ole valittu. Muussa tapauksessa palauttaa arvon true.
Tehtävä: Metodi paketoi kutsun järjestelmäfunktioon
ISteamUserStats::UploadLeaderboardScore. Kyseessä on Steamille lähetettävä asynkroninen kutsu, joka lataa nykyisen käyttäjän pisteet valittuna olevaan pistetaulukkoon. Metodi määrittää myös käytettävän kutsun palautusmetodin. Kutsu on tehtävä sen jälkeen, kun olet valinnut pistetaulukon käyttämällä
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()
Parametrit: –
Paluuarvot: –
Tehtävä: Metodi on takaisinkutsu, jota kutsutaan aina, kun yritetään lähettää pisteitä pistetaulukkoon Steamissä.
void CSteamLeaderboards::OnUploadScore(LeaderboardScoreUploaded_t *pCallback, bool bIOFailure)
{
if ( !pCallback->m_bSuccess || bIOFailure )
{
OutputDebugString( "Score could not be uploaded to Steam\n" );
}
}
DownloadScores()
Parametrit: –
Paluuarvot: False, jos pistetaulukkoa ei ole valittu. Muussa tapauksessa palauttaa arvon true.
Tehtävä: Metodi paketoi kutsun järjestelmäfunktioon
ISteamUserStats::DownloadLeaderboardEntries. Kyseessä on Steamille lähetettävä asynkroninen kutsu, joka lataa joukon merkintöjä valittuna olevasta pistetaulukosta. Tässä tapauksessa lataamme kymmenen merkintää: neljä ennen nykyistä käyttäjää, nykyinen käyttäjä ja viisi nykyisen käyttäjän jälkeen. Kutsua voi muuntaa palauttamaan minkä tahansa määrän merkintöjä mistä tahansa pistetaulukon kohdasta. Metodi määrittää myös käytettävän kutsun palautusmetodin. Kutsu on tehtävä sen jälkeen, kun olet valinnut pistetaulukon käyttämällä
FindLeaderboard().
bool CSteamLeaderboards::DownloadScores()
{
if (!m_CurrentLeaderboard)
return false;
// Lataa nykyisen käyttäjän tarkennettu pistetaulukko.
SteamAPICall_t hSteamAPICall = SteamUserStats()->DownloadLeaderboardEntries(
m_CurrentLeaderboard, k_ELeaderboardDataRequestGlobalAroundUser, -4, 5);
m_callResultDownloadScore.Set(hSteamAPICall, this,
&CSteamLeaderboards::OnDownloadScore);
return true;
}
OnDownloadScore()
Parametrit: –
Paluuarvot: –
Tehtävä: Metodi on takaisinkutsu, jota kutsutaan aina, kun yritetään ladata merkintöjä pistetaulukosta Steamissä. Jos tiedot ladattiin onnistuneesti, ne kopioidaan omaan merkintätaulukkoomme. Ladattujen merkintöjen määrä on tallennettu kohteeseen
m_nLeaderboardEntries.
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);
}
}
}
Vaihe 3 – Omaan peliisi integroiminen
Seuraavassa on täydellinen lista koodipätkistä, jotka sinun tulisi integroida asianmukaisiin kohtiin pelissä.
Määritykset ja globaalit muuttujat
Seuraavassa on yleisosoitin apuobjektiin ja lista tapauksista, joita tarvitaan pistetaulukkojen käsittelyssä.
...
#include "steam_api.h"
#include "SteamLeaderboards.h"
// Globaali pääsyoikeus pistetaulukon objekteihin
CSteamLeaderboards* g_SteamLeaderboards = NULL;
...
Alustaminen
Funktion
SteamAPI_Init kutsu alustaa koko Steamin, joten sitä on kutsuttava heti ensimmäiseksi. Jos kutsu onnistuu, luodaan aputoiminto-objekti.
...
// Alusta Steam
bool bRet = SteamAPI_Init();
// Luo SteamLeaderboards-objekti, jos Steamin alustus onnistui.
if (bRet)
{
g_SteamLeaderboards = new CSteamLeaderboards();
}
...
Takaisinkutsujen käsitteleminen
Jotta voimme varmistua, että kaikki Steam-takaisinkutsut tulevat käsitellyiksi, uusia viestejä on haettava säännöllisesti. Sen voi tehdä lisäämällä tämä kutsu pelisilmukkaan.
...
SteamAPI_RunCallbacks();
Sammutus
Koodisi sisältää todennäköisesti jo
SteamAPI_Shutdown-funktion kutsun. Se sammuttaa Steamin, joten sitä on kutsuttava ennen sovelluksen sulkeutumista. Lopuksi poistetaan aputoiminto-objekti.
...
// Sammuta Steam
SteamAPI_Shutdown();
// Poista SteamLeaderboards-objekti
if (g_SteamLeaderboards)
delete g_SteamLeaderboards;
...
Vaihe 4 – Testaus ja vianmääritys
Esimerkkikoodi tulostaa virheenkorjaustiedot debug-konsoliin, mikä voi auttaa ymmärtämään, mitkä kutsuista onnistuvat ja mitkä epäonnistuvat. Seuraavat ovat tyypillisiä virheilmoituksia ja korjausehdotuksia.
Sovelluksen käynnistyminen epäonnistui, koska steam_api.dll-tiedostoa ei löytynyt. Sovelluksen uudelleen asentaminen saattaa korjata ongelman.Varmista, että steam_api.dll-tiedosto on samassa hakemistossa kuin suoritettava tiedosto.
[S_API FAIL] SteamAPI_Init() epäonnistui; Steamin käynnissä olevaa esiintymää tai paikallista steamclient.dll-tiedostoa ei löytynyt.Steam-asiakasohjelma ei ole todennäköisesti käynnissä. Käynnistä Steam ja kirjaudu sisään.
[S_API FAIL] SteamAPI_Init() epäonnistui; sovellustunnusta ei löytynyt.Tiedosto steam_appid.txt ei todennäköisesti ole oikeassa paikassa. Lisää se lähdekansioon ja varmista, että siinä on sovellustunnusnumerosi.
