Steamworks-dokumentaatio
Tilastot ja saavutukset

Yleiskatsaus

Pelisi voi Steamin tilastojen ja saavutusten avulla helposti tarjota siirrettävää mutta pysyvää saavutusten ja tilastojen seurantaa käyttäjillesi. Käyttäjän tiedot on yhdistetty Steam-tiliin. Kunkin käyttäjän saavutuksia ja tilastoja voidaan muokata ja näyttää Steam-yhteisöprofiilissa.

Tilastojen ja saavutusten hyödyt

Saavutukset ovat pelaajillesi arvostettuja palkintoja, mutta niistä on myös muuta hyötyä. Ne kannustavat tiimityöhön ja pelaajien väliseen vuorovaikutukseen, ne tuovat peliin lisää ulottuvuutta ja palkitsevat käyttäjiä peliajasta.

Tilastoilla seurataan yksityiskohtia, kuten peliaikaa, vahvistuksia jne. Halutessasi voit käyttää tilastoja pelin sisäisten tietojen seuraamiseen, jotta voit esimerkiksi myöntää saavutuksen, joka pohjautuu useamman peli-istunnon tilastoihin useilta tietokoneilta.

Yleiskatsaus toteutukseen

Pelin tilastojen ja saavutusten määrittäminen

Saavutukset ovat sovelluskohtaisia ja määritetään sovelluksen ylläpitosivulla Steamworks-yhteistyökumppanisivustolla.

Pelisi voi tallentaa kolmen tyyppisiä tilastoja:
  • INT – 32-bittinen (etumerkillinen) kokonaisluku (esim. pelattujen pelien määrä)
  • FLOAT – 32-bittinen liukulukuarvo (esim. ajettujen mailien määrä)
  • AVGRATE – Liukuva keskiarvo. Lisätietoja: AVGRATE-tilastotyyppi

Steamworks-yhteistyökumppanisivusto tarjoaa käyttöliittymän, jonka avulla voit määrittää ja päivittää pelisi tilastoja ja saavutuksia. Sen avulla voit
  • määrittää alun tilastot ja saavutukset
  • lisätä tilastoja ja saavutuksia
  • päivittää saavutusten nimiä, kuvauksia ja kuvakkeita
  • päivittää tilastollisia muuttujia ja rajoituksia (enimmäis- ja vähimmäisarvot, liukuvan keskiarvon ikkunoiden koot jne.).
Tilastoilla on seuraavat ominaisuudet:
  • Tunnus – Jokaiselle tilastolle automaattisesti luotu, numeerinen tunnus.
  • Tyyppi – Tilaston tyyppi: INT, FLOAT tai AVGRATE.
  • API-nimi – Merkkijono, jonka avulla tilastoa käytetään ohjelmointirajapinnalla (API).
  • Määrittäjä – Määrittää, kuka voi muokata tilastoa. Oletuksena on sovellus. Lisätietoja on kohdassa Pelipalvelintilastot.
  • Vain kasvu – Jos määritetty, tilaston arvo voi kasvaa vain ajan myötä.
  • Enimmäismuutos - Jos määritetty, asettaa rajan määrälle, jonka tilaston arvo voi muuttua yhdestä SetStat-kutsusta toiseen.
  • Vähimmäisarvo – Jos määritetty, tilaston pienin mahdollinen numeroarvo. Vähimmäisarvona on oletusarvoisesti pienin, perustana oleva numerotyyppi (INT_MIN tai -FLT_MAX).
  • Enimmäisarvo – Jos valittu, tilaston suurin mahdollinen numeroarvo. Enimmäisarvona on oletusarvoisesti suurin, perustana oleva numerotyyppi (INT_MAX tai FLT_MAX).
  • Oletusarvo – Jos valittu, tämä oletusarvo määritetään tilastossa uudelle käyttäjälle. Jos tätä ei valita, oletusarvo on nolla.
  • Koottu – Jos määritetty, Steam pitää tilastosta yleistä kokonaistilastoa. Katso lisätietoja alla olevasta Yleistilastot-kohdasta.
  • Näyttönimi – Tilaston nimi, kun se näkyy Steam-yhteisössä. Se voidaan kääntää.
AVGRATE- tilastoilla on seuraava lisäominaisuus:
  • Ikkuna – "Liukuvan ikkunan" koko, jota käytetään tietojen keskiarvon laskemiseen.
Steam laskee automaattisesti AVGRATE-tilaston keskiarvon. Katso lisätietoja alla olevasta AVGRATE-kohdasta.

Saavutuksilla on seuraavat ominaisuudet:
  • Tunnus – Jokaiselle saavutukselle automaattisesti luotu, numeerinen tunnus.
  • API-nimi – Merkkijono, joka mahdollistaa pääsyn saavutukseen ohjelmointirajapinnan kautta.
  • Tulostilasto – Määrittää tilaston, jota käytetään yhteisössä tämän saavutuksen edistymispalkkina. Saavutus aukeaa automaattisesti, kun tilasto saavuttaa aukeamisarvon.
  • Näyttönimi – Nimi, joka saavutuksella on sovelluksen ilmoitusikkunoissa ja yhteisössä. Se voidaan kääntää.
  • Kuvaus – Yhteisössä näytettävä saavutuksen kuvaus. Se voidaan kääntää.
  • Määrittäjä – Määrittää, kuka voi avata saavutuksen. Oletuksena on sovellus. Lisätietoja on kohdassa Pelipalvelintilastot.
  • Piilotettu – Jos tosi, "piilotettua" saavutusta ei näytetä lainkaan käyttäjän yhteisösivulla, ennen kuin käyttäjä on saavuttanut sen.
  • Saavutettu – Kuvake, joka näytetään, kun saavutus on saavutettu.
  • Saavuttamaton – Kuvake, joka näytetään, kun saavutusta ei ole vielä saavutettu.

Alla on saavutusluettelo esimerkkipelistä Steamworks API Example Application (SpaceWar):
achievements_spacewar.png

Tilastojen ja saavutusten käyttäminen

Tilastojen ja saavutusten käyttö pelissä:

AVGRATE-tilastotyyppi

Tämän tyyppisessä tilastossa on ainutlaatuisia ja erittäin hyödyllisiä toimintoja, mutta se edellyttää hieman yksityiskohtaisempaa selostusta.

Otetaan esimerkiksi tilanne, jossa halutaan seurata tavanomaista tilastoa, kuten "Tunnin aikana ansaitut pisteet". Yksi lähestymistapa on käyttää kahta tilastoa, INT "kokonaispisteet" ja FLOAT "kokonaispeliaika tunteina", ja jakaa sitten pisteet ajalla. Näin saadaan tunnin aikana ansaitut pisteet.

Tämän toteutuksen huono puoli on se, että kun pelaajalle on kertynyt merkittävä määrä peliaikaa, laskettu keskiarvo muuttuu erittäin hitaasti. Itse asiassa mitä enemmän pelaaja pelaa peliä, sitä vähemmän keskiarvo mukautuu tilanteeseen. Jos käyttäjä on pelannut 100 tuntia, laskettu keskiarvo on jäljessä noin 50 tuntia tästä peliajasta. Jos pelaajan taidot paranevat, hän ei näe tuntikohtaisissa pisteissä toivomaansa edistystä.

AVGRATE-tilastotyypillä voit toteuttaa "liukuva ikkuna" -tehosteen keskiarvoon. Voit esimerkiksi käyttää vain muutamaa edellistä pelattua tuntia, jotta tilastot kuvaavat paremmin pelaajan taitojen nykyistä tasoa.

Määritetään "tuntikohtaisia pisteitä" varten AVGRATE-tilasto, jossa vain edelliset 20 pelituntia vaikuttavat keskiarvoon. Tämä tehdään seuraavasti:
  • Huomaa! Koska kyseessä on tuntikohtainen tilasto, kaikki aikamuuttujat merkitään tunteina. Tämä koskee tilaston Ikkuna-ominaisuutta ja myös "dSessionLength"-muuttujaa, joka on määritetty alla olevalle UpdateAvgRateStat-toiminnolle.
  • Luo "AvgPointsPerHour"-niminen AVGRATE-tilasto ja ikkunaominaisuus arvolla 20,00 (muista, että se on "tunteina")
  • Tee sopivissa kohdissa peliä kutsu ISteamUserStats::UpdateAvgRateStat seuraavilla muuttujilla:
    • pchName – "AvgPointsPerHour"
    • flCountThisSession – Pelaajan ansaitseminen pisteiden määrä viimeisimmän UpdateAvgRateStat-metodin kutsun jälkeen.
    • dSessionLength – Peliajan määrä viimeisimmän UpdateAvgRateStat-kutsun jälkeen. Yksikön on oltava sama kuin tilastojen ikkunaominaisuudessa. Tässä tapauksessa yksikkö on siis tunti.
  • Jos pelaaja esimerkiksi ansaitsee 77 pistettä viimeisellä kierroksella, joka kesti 0,225 tuntia (13,5 minuuttia), suorita seuraava kutsu: SteamUserStats()->UpdateAvgRateStat( "AvgPointsPerHour", 77, 0.225 )
Edellä olevassa esimerkissä Steam yhdistää nykyisten kierrosten keskiarvon 342,2 pistettä tunnissa (77 jaettuna 0,225:llä) edeltävään arvoon. Tulokseksi saadaan pelaajan viimeksi pelaamien 20 pelitunnin kokonaiskeskiarvo. Jos tämä olisi ensimmäinen kerta, kun tilasto päivitetään nykyiselle käyttäjälle, nykyinen arvo olisi 342,2.

Tässä esimerkissä käytetään yksikkönä tunteja, mutta voit käyttää mitä tahansa aikayksikköä. Muista, että valitsemaasi aikayksikköä on käytettävä johdonmukaisesti "dSessionLength"-muuttujan perustana sekä ikkunaominaisuudessa.

Muiden käyttäjien tilastojen noutaminen

Voit noutaa toisen käyttäjän tilastot ISteamUserStats::RequestUserStats -kutsulla. Saat käyttäjän tiedot kutsuilla ISteamUserStats::GetUserStat, ISteamUserStats::GetUserAchievement ja ISteamUserStats::GetUserAchievementAndUnlockTime. Kun toinen käyttäjä lataa uusia tilastoja, dataa ei päivitetä automaattisesti. Päivitä siis tiedot ISteamUserStats::RequestUserStats-kutsulla.

Jotta muistia ei kuormitettaisi liikaa, käytetään (vanhimmille tiedoille) LRU-välimuistia. Muiden käyttäjien tilastoja poistetaan välillä. Kun välimuisti kuormittuu, lähetetään automaattisesti ISteamUserStats::UserStatsUnloaded_t-vastakutsu. Kun tämä vastakutsu lähetetään, kyseisen käyttäjän tilastoja ei saa, ennen kuin kutsu ISteamUserStats::RequestUserStats on tehty uudelleen.

Offline-tila

Steam säilyttää tilasto- ja saavutustietoja paikallisessa välimuistissa, jotta ohjelmointirajapinnan käyttö onnistuu offline-tilassa. Offline-tilassa vahvistamatta jääneet tilastotiedot tallennetaan seuraavalle kerralle, kun käyttäjä on jälleen online-tilassa. Steam yhdistää pelaajan saavutukset automaattisesti ja valitsee tilastot, joissa käyttäjän peli on pidemmällä, jos muutoksia on tehty useammalla kuin yhdellä koneella. Steam säilyttää tilastotietoja paikallisessa välimuistissa, eikä pelin ei tarvitsisi tehdä sitä kiintolevyllä. Välimuistien välille syntyy synkronointiristiriitoja, jolloin käyttäjät saattavat turhautua, koska edistyminen pelissä näyttää nollautuneen.

Pelipalvelintilastot

ISteamUserStats-rajapinnan tavoin ISteamGameServerStats-ohjelmointirajapinta on tarkoitettu pelipalvelimille. Ne voivat hakea käyttäjien tilastoja sovellusten tavoin (kuvattu edellä). Tilasto- ja palkintosaavutusten määritys onnistuu mutta ainoastaan, jos "Määrittäjä"-ominaisuudeksi on määritetty GS (pelipalvelin) tai virallinen GS. Pelipalvelimet ja viralliset pelipalvelimet eroavat toisistaan siten, että viralliset pelipalvelimet ovat isännöitäviä ja ylläpidettäviä palvelimia. Virallisten pelipalvelimien käyttäminen tilastojen määrityksessä auttaa ehkäisemään huijauksia, sillä pelaajat voivat muokata omia pelipalvelimiaan tai huijata toimivansa pelipalvelimena. Määritä viralliset pelipalvelimet antamalla niiden IP-osoitealueet täällä.

Sovellukset eivät voi määrittää tilastoja ja saavutuksia, joita pelipalvelimet määrittävät. Pelipalvelimet voivat määrittää tilastoja ja saavutuksia vain käyttäjille, jotka ovat tällä hetkellä pelaamassa palvelimella. Jos käyttäjä lähtee palvelimelta, lopulliset tilastot määritetään lyhyen lisäajan aikana, mutta tämän jälkeen uudet lataukset kielletään. Tämän tarkoituksena on varmistaa yhtenäisyys ja estää haitallisia pelipalvelimia määrittämästä kenenkään tilastoja. Siksi on tärkeää, ettei tilastoja määritetä vasta kierroksen lopuksi. Tilastoja kannattaa määritellä koko ajan, jotta voit tallentaa ne käyttäjän lopettaessa.

Käyttäjät saavat päivitykset automaattisesti, kun heidän tilastonsa muuttuvat pelipalvelimella. Palvelimen lähettämiä muiden käyttäjien tilastoja ei kuitenkaan päivitetä automaattisesti, joten tilastot voivat olla vanhentuneita.

Tilastojen nollaaminen

Tilastot ja saavutukset saatetaan poistaa tililtä kehittämisen aikana testitarkoituksessa. Voit poistaa tilastot tililtä tekemällä ISteamUserStats::ResetAllStats-kutsun. Jos haluat poistaa myös saavutukset bAchievementsToo-kutsulla, ehtona tulee olla tosi. Muista kutsun jälkeen iteroida tilastot ja saavutukset uudelleen. Nollaa myös muistiin ladatun pelin tila. Kaikkien käyttäjien tilastojen ja saavutusten poistamiseksi ei ole mitään yleiskeinoa. Yksi syy on se, että vaikka kaikki tiedot nollattaisiin, meneillään olevat pelit eivät välttämättä havaitsisi poistoa vaan kirjoittaisivat arvot takaisin muistiin. Onneksi peliisi voi helposti tehdä yleisen tietojen poistamisjärjestelmän. Tee se seuraavasti:
  • Määritä tilasto, jonka nimi on esimerkiksi "Versio".
  • Lisää peliin kovakoodatun tilaston versionumero.
  • Kun tilastot on ladattu, vertaa "Versio"-tilastoa kovakoodattuun versionumeroon.
  • Jos versiot eivät ole yhtäpitäviä, tee ISteamUserStats::ResetAllStats-kutsu. Sen jälkeen määritä "Versio"-tilasto kovakoodattuun numeromuotoon.
Tällä tavalla voit tehdä yleisen poiston muuttamalla kovakoodatun tilaston versionumeroa. Kaikki tilastot ja saavutukset nollataan, kun käyttäjät hankkivat uuden koontiversion.

Tilastojen yhtenäisyys

Jos tilastoissa on ongelmia, kannattaa miettiä niiden syytä. Käytössäsi voi esimerkiksi olla seuraavat kolme tilastoa: "VoitetutPelit", "HävitytPelit", ja "PelatutPelit". Kaikesta huolimatta tilastojen synkronointi ei aina onnistu. Tässä tapauksessa se voi johtaa siihen, ettei voitettuja ja hävittyjä pelejä lasketa pelattuihin peleihin. Jos tätä yritetään ratkaista poistamalla "HävitytPelit" ja laskemalla niiden määrä vähentämällä pelatuista peleistä voitetut ("PelatutPelit" - "VoitetutPelit"), "HävitytPelit"-arvo saattaakin olla negatiivinen. Tässä tapauksessa kannattaa poistaa "PelatutPelit"-tilasto ja käsitellä se näin: "VoitetutPelit" + "HävitytPelit".

Yleistilastot

Tilastot voidaan merkitä kerätyiksi hallintasivulla, jotta Steam kirjaa kaikkien käyttäjien arvojen kokonaismäärän. Tällä voidaan hankkia tietoja talouden kokonaisrahamäärästä, tapoista, suosikkiaseista ja -kartoista ja parhaiten pärjäävästä tiimistä. Toisaalta tätä ei pitäisi käyttää "EnitenTappoja"-tyyppisissä tilastoissa, sillä niiden laskemisessa useammille käyttäjille ei ole merkitystä. Käyttäjillä olevat tilastot ovat alttiita manipuloinnille. Tämän vuoksi on erittäin tärkeää, että koottuja tilastoja käytettäessä asetetaan tarkat rajat vähimmäis-, enimmäis-, vain kasvu- (jos tarpeen) ja enimmäismuutos -arvoille. Enimmäismuutoksella on erityinen merkitys kerätyissä tilastoissa. Kun uusi arvo saapuu, yleisarvo muuttuu korkeintaan enimmäismuutoksen verran. Tämä rajoittaa sitä, miten nopeasti huijari pystyy vaikuttamaan yleismääriin.

Jotta pääsisit tarkastelemaan kunkin yleistilaston kokonaismääriä, tee ISteamUserStats::RequestGlobalStats- ja ISteamUserStats::GetGlobalStat -kutsut. Voit pyytää historiatietoja tietyiltä päiviltä ISteamUserStats::RequestGlobalStats-kutsulla. Historiatiedoilla tarkoitetaan määrää, jonka tilasto muuttui päivittäin. Pääset historiatietoihin tekemällä ISteamUserStats::GetGlobalStatHistory-kutsun.

Voit myös pyytää globaaleja saavutusten suoritusprosentteja sovelluksesta. Suorita ensin kutsu ISteamUserStats::RequestGlobalAchievementPercentages. Iteroi sen jälkeen saavutukset järjestyksessä, jossa eniten suoritetut tulevat ensin ja vähiten suoritetut viimeisenä. Tee se ISteamUserStats::GetMostAchievedAchievementInfo- ja ISteamUserStats::GetNextMostAchievedAchievementInfo -kutsuilla. Voit myös hakea tietyn saavutuksen suoritusprosentin ISteamUserStats::GetAchievementAchievedPercent-kutsulla.

Steam-yhteisö

Kun pelisi on julkaistu, tiedot yksittäisten ja yleisten saavutusten edistymisestä näytetään Steam-yhteisössä. Jokaisella pelaajalla on linkki yhteisöprofiilistaan sivulle, jossa esitellään hänen saavutuksensa ja mitä saavutuksia hän ei ole vielä avannut.
HUOMAA! Saavutuksiasi ei näytetä, ennen kuin sovelluksesi on jossain määrin yhteisön nähtävissä.

Jokainen saavutus on luetteloitu siten, että sen kohdalla on sopiva kuvake ja Steamworks-ohjauspaneelin kaltaisesti määritetty nimi ja kuvaus. Jos saavutuksen nimi ja kuvaus on käännetty käyttäjän valitsemalle kielelle, ne näytetään kyseisellä kielellä.

Myös tältä sivulta ja pelisi Steam-pääsivulta löytyy linkki pelisi yleisiin saavutustilastoihin. Niissä näkyy Steam-pelaajien prosenttimäärä, jotka ovat saavuttaneet pelin jokaisen saavutuksen – ensin yleisimmät ja lopuksi harvinaisimmat saavutukset. Tästä on iloa pelaajille ja hyötyä sinulle kehittäjänä. Voit selvittää, ovatko erityishaasteesi riittävän vaikeita. Vai ovatko ne kenties liian vaikeita? (Nämä tiedot ovat saatavilla myös Myynti- ja aktivointiraporttien sivustolla.)

Onko sinulla muuta kysyttävää?

Kysy lisää Tilastot ja saavutukset -keskusteluryhmässä.