Steamworks-dokumentation
Statistikker og præstationer

Oversigt

Steam-statistikker og præstationer gør det nemt for dit spil at spore dine brugeres statistikker og præstationer. Brugernes data er forbundet med deres Steam-konto, og den enkelte brugers præstationer og statistikker kan formateres og vises på brugerens Steam-fællesskabsprofil.

Hvad kan de bruges til?

Udover at brugere, som spiller dit spil, vil sætte stor pris på præstationer, er præstationer også en god måde at opfordre til og belønne samarbejde og spillerinteraktion på. Det giver ekstra dimensionalitet i spilmål og belønner brugere for at bruge mere tid i spillet.

Statistikker sporer præcise stykker information, for eksempel spilletid, antal anvendte power-ups osv. Du kan vælge at bruge dem til ganske enkelt at spore interne spildata – så du for eksempel kan tildele en præstation baseret på gameplay-statistikker fra brugere over flere sessions og på tværs af computere.

Implementeringsoversigt

Definer dit spils statistikker og præstationer

Præstationer er applikationsspecifikke og konfigureres på siden "App-administrator" på Steamworks-partnersiden.

Der er tre typer statistikker, som dit spil kan lagre:
  • INT – Et 32-bit (signeret) heltal (for eksempel antal spillede spil)
  • FLOAT – En 32-bit flydende talværdi (for eksempel antal kørte kilometer)
  • AVGRATE – Et glidende gennemsnit. Se: AVGRATE-statistiktype

Steamworks-partnersiden har en grænseflade til definering og opdatering af dit spils statistikker og præstationer. Med den kan du:
  • Definere de indledende statistikker og præstationer
  • Tilføje yderligere statistikker og præstationer
  • Opdatere præstationsnavne, -beskrivelser og -ikoner
  • Opdatere statistikparametre og begrænsninger (maksimum- og minimumværdier, vinduestørrelse for glidende gennemsnit osv.)
Statistikker har følgende egenskaber:
  • ID – Et automatisk genereret numerisk ID for hver statistik.
  • Type – Statistikkens type: INT, FLOAT eller AVGRATE.
  • API name – Den streng, der bruges til at tilgå statistikken vha. API'en.
  • Set by – Angiver, hvem der kan modificere statistikken. Er som standard "Klient". Læs mere: Statistik over spilservere.
  • Increment only – Hvis dette er angivet: Statistikken kan kun stige i værdi over tid.
  • Max change – Hvis dette er angivet: Grænse for, hvor meget statistikkens værdi kan ændre sig fra ét SetStat-opkald til det næste.
  • Min value – Hvis dette er angivet: Den mindste numeriske værdi, som denne statistik kan have. Som standard er det minimum for den underliggende numeriske type (INT_MIN eller -FLT_MAX).
  • Max value – Hvis dette er angivet: Den maksimale numeriske værdi, som denne statistik kan have. Som standard er det maksimum for den underliggende numeriske type (INT_MAX eller -FLT_MAX).
  • Default value – Hvis dette er angivet: Standardværdien, som denne statistik vil have til at starte med for en ny bruger. Hvis intet angives, er standardværdien 0.
  • Aggregated – Hvis dette er angivet: Steam gemmer den samlede globale værdi for denne statistik. Se "Globale statistikker" nedenfor for mere information.
  • Display name – Navnet på statistikken, når den vises i din app.
AVGRATE: Disse statistikker har følgende yderligere egenskaber:
  • Vindue – størrelsen på det "glidende vindue", der bruges til at beregne gennemsnittet af dine data.
En AVGRATE-statistik er en statistik, som Steam automatisk beregner gennemsnittet af. Se sektionen AVGRATE nedenfor for mere information.

Præstationer har følgende egenskaber:
  • ID – Et automatisk genereret numerisk ID for hver præstation.
  • API name – Den streng, der bruges til at tilgå præstationen vha. API'en.
  • Progress stat – Angiver en statistik, som bruges som en fremskridtsbjælke i fællesskabet for denne præstation. Præstationen låses også automatisk op, når statistikken når oplåsningsværdien.
  • Display name – Præstationens navn i pop op-vinduer i klienten og i fællesskabet. Kan lokaliseres.
  • Description – En beskrivelse af præstationen, som vises i fællesskabet. Kan lokaliseres.
  • Set by – Angiver, hvem der kan oplåse præstationen. Er som standard "Klient". Læs mere: Statistik over spilservere.
  • Hidden? – Hvis denne er true, vises en "skjult" præstation ikke på brugerens fællesskabsside (overhovedet), før de har opnået præstationen.
  • Achieved icon – Ikon, som vises, når præstationen er opnået.
  • Unachieved icon – Ikon, som vises, når præstationen endnu ikke er opnået.

Det følgende er en liste over præstationer fra Steamworks-API-eksempel på applikation (SpaceWar):
achievements_spacewar.png

Særlige overvejelser

  • Præstationsnavne og ikoner skal være alderspassende.
  • Som standard er spil begrænset til 100 præstationer til at starte med. Når din applikation når tærsklen for profilegenskaber, kan du tilføje flere præstationer.

Sådan bruges de

Adgang til statistikker og præstationer fra dit spil:

AVGRATE-statistiktype

Denne type statistik giver unik og meget nyttig funktionalitet, men det kræver lidt flere oplysninger for at forklare det.

Overvej en situation, hvor du ønsker at spore en gennemsnitlig statistik såsom "Point optjent pr. time". En tilgang kan være at have to statistikker: En INT "SamletPoint" og en FLOAT "SamletAntalSpilledeTimer" og derefter dividere point med tiden, som det tog at få pointene.

Ulempen ved denne implementering er, at når spilleren har akkumuleret en betydelig spilletid, vil det beregnede gennemsnit ændre sig ekstremt langsomt. Faktisk jo mere brugeren spiller spillet, desto mindre vil gennemsnittet flytte sig. Hvis brugeren har brugt 100 timer på at spille spillet, vil det udregnede gennemsnit have en "forsinkelse" på omkring 50 timer af dette. Hvis spilleren forbedrer sine evner, ser de ikke samme stigning i point pr. time, som de ville forvente.

AVGRATE-statistiktypen gør det muligt at implementere en effekt med en skydevindueseffekt med gennemsnittet. For eksempel kan du vælge kun at bruge de forgangne par timer af gameplayet, så statistikken afspejler spillerens nuværende færdighedsniveau mere præcist.

Lad os opsætte en AVGRATE-statistik til at implementere "point pr. time", hvor kun de seneste 20 timers gameplay påvirker værdien. Dette kræver følgende:
  • Bemærk, at fordi gennemsnittet bliver "pr. time", vil tidsenheden på alle tidsparametre, som er tilknyttet denne statistik, være i "timer". Dette gælder for vinduets egenskab på statistikken selv og også for parameteren "dSessionLength", som sendes til UpdateAvgRateStat nedenfor.
  • Opret en AVGRATE-statistik med navnet "AvgPointsPerHour" og en vinduesegenskab på 20,0 (husk, det er i "timer").
  • Kald ISteamUserStats::UpdateAvgRateStat på passende tidspunkter i dit spil med følgende parametre:
    • pchName – "AvgPointsPerHour"
    • flCountThisSession – Antallet af point, spilleren har optjent siden sidste kald til UpdateAvgRateStat.
    • flCountThisSession – Mængden af spilletid siden sidste kald til UpdateAvgRateStat. Denne enhed bør være det samme som enheden på statistikkens vinduesegenskab. I dette tilfælde er det "timer".
  • For eksempel hvis spilleren har optjent 77 point i den sidste runde, som varede 0,225 timer (13,5 minutter), ville det være SteamUserStats()->UpdateAvgRateStat( "AvgPointsPerHour", 77, 0,225 )
I ovenstående eksempel tager Steam det aktuelle rundegennemsnit på 342,2 point pr. time (77 divideret med 0,225) og forener det med den tidligere værdi. Resultatet afspejler det samlede gennemsnit for spillerens sidste 20 timers spilletid. Hvis dette var den første gang, at statistikken blev opdateret for den pågældende bruger, vil den nuværende værdi være 342,2.

Dette eksempel bruger "timer" som tidsenhed, men du kan bruge den enhed, der passer dig bedst. Du skal bare huske at være konsekvent med at bruge samme enhed som grundlag for "dSessionLength" samt for vinduets egenskab.

Hentning af statistikker for andre brugere

Du kan bruge ISteamUserStats::RequestUserStats til at få statistikker for andre brugere. Du kan derefter bruge ISteamUserStats::GetUserStat, ISteamUserStats::GetUserAchievement og ISteamUserStats::GetUserAchievementAndUnlockTime til at hente data for den pågældende bruger. Disse data bliver ikke opdateret automatisk, når den anden bruger uploader nye statistikker, så for at opdatere dataene skal du bare kalde ISteamUserStats::RequestUserStats igen.

For at undgå, at dette bruger for meget hukommelse, bruges en LRU-cache (Least Recently Used-cache, dvs. de først anvendte), og andre brugerstatistikker fjernes af og til. Når dette sker, sendes der automatisk et ISteamUserStats::UserStatsUnloaded_t-tilbagekald. Når dette tilbagekald er blevet sendt, vil den angivne brugers statistik ikke være tilgængelig, før ISteamUserStats::RequestUserStats kaldes igen.

Offlinetilstand

Steam gemmer en lokal cache af statistikker og præstationsdata, så API'er kan bruges som normalt i offlinetilstand. Alle statistikker, som ikke kan udføres, gemmes til næste gang, brugeren er online igen. Hvis der har været modifikationer på mere end én maskine, kombinerer Steam automatisk præstationer og vælger det sæt af statistikker, som har mest fremgang. Fordi Steam beholder en lokal cache af statistikdataene, er det ikke nødvendigt for spillet at gennem en lokal cache af dataene på disken. Sådanne caches kommer ofte i konflikt, og når dette sker, ligner det, at brugeres fremgang er blevet tilbageført, hvilket kan være meget frustrerende.

Statistik over spilservere

Parallelt med ISteamUserStats er der ISteamGameServerStats til spilservere. Disse kan hente statistikker for brugere på samme måde, som klienter kan (beskrevet ovenfor). De kan også angive statistikker og tildele præstationer, men kun hvis "Sæt med" er indstillet til GS (game server) eller Official GS. Forskellen mellem spilservere og officielle spilservere er, at officielle spilservere er servere, som du hoster og kontrollerer. Brug af officielle spilservere til at angive statistikker øger sikkerheden mod snyd, da brugere muligvis kan ændre deres egne spilservere eller lave en falsk spilserver. For at definere officielle spilservere kan du indtaste servernes IP-område her .

Statistikker og præstationer kan indstilles af spilservere, men kan ikke indstilles af klienter. Spilservere kan kun indstille statistikker og præstationer for brugere, som spiller på serveren. Hvis brugeren forlader serveren, er der et kort tidsrum, hvor de sidste statistikker kan angives, men derefter bliver nye uploads afvist. Dette er for at hjælpe med at sikre konsistens og undgå, at en ondsindet spilserver når som helst kan indstille andres statistikker. Med denne restriktion er det derfor vigtigt ikke at vente til slutningen af en runde, før statistikkerne indstilles. Angiv dem undervejs, så de kan gemmes, når en bruger forlader spillet.

Klienter får automatiske opdateringer, når en spilserver ændrer sine statistikker. Men, som med klienter, bliver statistikker, som loades af serveren for andre brugere, ikke automatisk opdateret og kan derfor få timeout.

Nulstilling af statistikker

Under udvikling er det ofte tilfældet, at man ønsker at rydde alle statistikker og præstationer på en konto eller alle konti, fordi det hjælper med testning. For at rydde statistikker for en konto skal du kalde ISteamUserStats::ResetAllStats med bAchievementsToo sat til true for også at rydde præstationer. Efter kaldet skal du huske at iterere dine statistikker og præstationer igen og nulstille hukommelsen i spiltilstanden. Det er ikke muligt at rydde statistikker og præstationer globalt for alle brugere. En af grundene til dette er, at selv hvis global rydning blev udført, vil spil, som allerede er i gang, måske ikke bemærke rydningen og skrive værdier ind igen fra hukommelsen. Der er heldigvis en nem måde at indbygge et globalt rydningssystem i dit spil. Sådan gør du:
  • Definer en statistik med et navn såsom "Version".
  • Indsæt et hardcoded statistikversionsnummer i spillet
  • Når statistikkerne er blevet indlæst, skal du sammenligne "Version"-statistikken med det hardcodede versionsnummer.
  • Hvis de ikke matcher, skal du kalde ISteamUserStats::ResetAllStats og derefter sætte "Version"-statistikken til det hardcodede nummer.
På denne måde kan du bare ændre det hardcodede statistikversionsnummer, når du vil rydde alt globalt. Den globale rydning sker, når folk får det nye build.

Konsistente statistikker

Den bedste fremgangsmåde er at tænke over, hvordan relaterede statistikker kunne blive inkonsekvente. Det kan eksempelvis være, at du har tre statistikker: "GamesWon", "GamesLost" og "GamesPlayed". Trods de bedste intentioner kan og vil statistikker nogle gange ikke være synkroniserede med hinanden. I dette tilfælde kan det føre til, at antallet af vundne og tabte spil ikke går op med det samlede antal spillede spil. Hvis dette bliver løst ved at fjerne statistikken "GamesLost" og i stedet behandle den som "GamesPlayed" - "GamesWon", kan en inkonsistens forårsage, at "GamesLost" bliver negativ. I dette tilfælde er det bedst at droppe statistikken "GamesPlayed" og behandle det som "GamesWon" + "GamesLost".

Globale statistikker

Statistikker kan markeres som samlet på administratorsiden for at fortælle Steam, at der skal udregnes et globalt samlet tal for alle brugeres værdier for denne statistik. Dette kan bruges til at hente data om det samlede beløb i økonomien, samlede antal drab, favoritvåben, yndlingsbaner, og hvilke hold der har tendens til at klare sig bedst. Modsat bør dette ikke bruges til statistikker som "MostKills", da det ikke vil give mening at lægge dette sammen for mange brugere. Da statistikker er i hænderne på brugerne, kan disse data blive udsat for manipulation. Derfor er det vigtigt, når der bruges aggregerede statistikker, at man sætter gode grænser for minimumsværdi, maks.-værdi, kun trinvis stigning (hvis relevant) og maksimal ændring. Maksimal ændring har en særlig betydning for aggregerede statistikker. Når en ny værdi uploades, ændres den globale værdi ikke mere end den maksimale ændringsværdi. Dette begrænser, hvor hurtigt en snyder kan påvirke de samlede globale statistikker.

For at tilgå de samlede globale statistikker skal du kalde ISteamUserStats::RequestGlobalStats og derefter ISteamUserStats::GetGlobalStat for hver globale statistik. Du kan også spørge efter en ISteamUserStats::RequestGlobalStats for at få et specifikt antal dages historik. Historikken viser, hvor meget statistikken ændrede sig hver dag. Du kan se historikken med ISteamUserStats::GetGlobalStatHistory.

Du kan også anmode om procentsatser over globale præstationer fra klienten. For at gøre dette skal du først kalde ISteamUserStats::RequestGlobalAchievementPercentages. Derefter skal du iterere præstationerne i rækkefølge fra de mest gennemførte til de mindst gennemførte ved at kalde ISteamUserStats::GetMostAchievedAchievementInfo og ISteamUserStats::GetNextMostAchievedAchievementInfo. Du kan også få gennemførelsesprocenten for en bestemt præstation ved at kalde ISteamUserStats::GetAchievementAchievedPercent.

Testning


Før din app udgives, kan du ikke se, hvilke præstationer der er blevet optjent i Steam-fællesskabet eller -biblioteket. Din app skal have en måde at sende ud, hvilke præstationer der er blevet optjent for brugeren.

Du kan bruge Steam-klientkonsollen til at rydde en præstation eller statistik uden at tilføje kode til dit spil. Kør med steam.exe -console og derefter:
  • achievement_clear <appid> <achievement name>
  • reset_all_stats <appid>

Steam-fællesskabet

Når dit spil er blevet udgivet, vises oplysninger om individuelle og globale præstationsfremgange i Steam-fællesskabet. Hver spiller vil have et link på deres fællesskabsprofil, som fører til en side, der viser, hvilke præstationer de har opnået, og hvad de stadigvæk mangler at låse op for.
BEMÆRK: Præstationer vises ikke, før din app er synlig i en eller anden form i fællesskabet.

Hver præstation vises på listen med et passende ikon samt det navn og den beskrivelse, der er angivet i Steamworks-kontrolpanelet. Hvis præstationens navn og beskrivelse er blevet oversat til det sprog, som brugeren har valgt, vises begge på dette sprog.

Der vil også være et link fra denne side og et fra dit spils primære Steam-side til at angive globale præstationsstatistikker for dit spil. Det viser procenten af Steam-spillere i spillet, som har modtaget hver præstation, i rækkefølge fra den mest almindelige til den mest sjældne præstation. Dette er sjovt for spillere at se, og det er også en god resurse for dig som udvikler, så du eksempelvis kan se, om dine særlige udfordringer er svære nok. Eller måske de er for svære? (Disse oplysninger er også tilgængelige på siden med salgs- og aktiveringsrapporter).

Flere spørgsmål?

Stil spørgsmål i diskussionsforummet for statistikker og præstationer