Uden tilknytning

Hjem Dokumentation og hjælp
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: Statistiktypen AVGRATE

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: Spilserverstatistikker.
  • 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 Steam-fællesskabet. Kan lokaliseres.
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 statistik.
  • 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: Spilserverstatistikker.
  • 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 Example Application (SpaceWar):
achievements_spacewar.png

Sådan bruges de

Adgang til statistikker og præstationer fra dit spil:

Statistiktypen AVGRATE

Denne type statistik giver en unik og meget nyttig funktionalitet, men den kræver lidt mere forklaring.

Lad os sige, at du vil spore en gennemsnitsstatistik, for eksempel "Optjente point pr. time". En måde at gøre det på vil være at have to statistikker, en INT "PointIAlt" og en FLOAT "TimersSpilletidIAltPlayTimeHours", og dividere point med tid for at få "point pr. time".

Ulempen ved denne implementering er, at når spilleren har akkumuleret en betydelig spilletid, vil det beregnede gennemsnit ændre sig meget, meget langsomt. Faktisk vil gennemsnittet ændre sig mindre og mindre, jo mere brugeren spiller. Hvis brugeren har brugt 100 timer på at spille, vil det beregnede gennemsnit "halte" med ca. 50 timer. Hvis brugeren bliver dygtigere, vil vedkommende ikke se den forventede stigning i "point pr. time".

Med statistiktypen AVGRATE kan du implementere et "glidende vindue" i gennemsnittet. Du kan for eksempel nøjes med at bruge de sidste par timers gameplay, så statistikken afspejler spillerens nuværende færdighedsniveau mere nøjagtigt.

Lad os indstille AVGRATE-statistikken "point pr. time", hvor kun de forudgående 20 timers gameplay påvirker værdien. Gør følgende:
  • Bemærk: Eftersom gennemsnittet vil være "pr. time", skal tidsenheden for alle parametre, som er knyttet til denne statistik være "timer". Dette gælder for vinduesegenskaben i selve statistikken og også for parametren "dSessionLength", som sendes til UpdateAvgRateStat nedenfor.
  • Opret en AVGRATE-statistik kaldet "AvgPointsPerHour" og en vinduesegenskab på 20.0 (i timer).
  • På relevante steder i dit spil skal du kalde ISteamUserStats::UpdateAvgRateStat med følgende parametre:
    • pchName – "AvgPointsPerHour"
    • flCountThisSession – Antal point, som spilleren har optjent siden sidste kald til UpdateAvgRateStat.
    • dSessionLength – Mængde spilletid siden sidste kald til UpdateAvgRateStat. Enheden skal være den samme som enheden i statistikkens vinduesegenskab. I dette tilfælde "timer".
  • Hvis spilleren for eksempel har optjent 77 point i sidste runde, og runden varede 0,225 timer (13,5 minutter), ville det være SteamUserStats()->UpdateAvgRateStat( "AvgPointsPerHour", 77, 0.225 )
I ovenstående eksempel tager Steam den aktuelle rundes gennemsnit på 342,2 point pr. time (77 divideret med 0,225 ) og kombinerer det med den tidligere værdi. Resultatet afspejler det samlede gennemsnit af spillerens sidste 20 timers spilletid. Hvis dette var første gang, at statistikken blev opdateret for den aktuelle bruger, vil den aktuelle værdi være 342,2.

I eksemplet anvendes "timer" som tidsenhed, men du kan bruge den tidsenhed, du vil. Bare husk, at den pågældende enhed skal bruges konsekvent som udgangspunkt for "dSessionLength" samt som vinduesegenskab.

Sådan får du statistikker for andre brugere

Du kan bruge ISteamUserStats::RequestUserStats for at få statistikker for en anden bruger. Du kan bruge ISteamUserStats::GetUserStat, ISteamUserStats::GetUserAchievement og ISteamUserStats::GetUserAchievementAndUnlockTime for at få data for den pågældende bruger. Disse data opdateres ikke automatisk, når den anden bruger uploader nye statistikker, så for at opdatere dataene skal du kalde ISteamUserStats::RequestUserStats igen.

For at undgå, at dette bruger for meget hukommelse, bruges en LRU-cache (Least Recently Used, dvs. de først anvendte), og andre brugeres statistikker fjernes af og til. Når dette sker, sendes der automatisk et ISteamUserStats::UserStatsUnloaded_t-tilbagekald. Når tilbagekaldet sendes, vil den angivne brugers statistikker være utilgængelige, indtil ISteamUserStats::RequestUserStats kaldes igen.

Offlinetilstand

Steam vedligeholder en lokal cache af statistik- og præstationsdata, så API'erne kan bruges som normalt i offlinetilstand. Statistikker, som ikke kan udføres, gemmes til næste gang, brugeren er online. Hvis der er sket modifikationer på mere end én maskine, fletter Steam automatisk præstationerne og vælger statistiksættet med størst fremskridt. Eftersom Steam vedligeholder en lokal cache af statistikdata, er det ikke nødvendigt for spillet også at vedligeholde en lokal cache af data på disken. Sådanne caches kommer ofte i konflikt med hinanden, og når det sker, ser det for brugerne ud som om, at deres fremskridt er blevet tilbageført, hvilket er en meget frustrerende oplevelse.

Spilserverstatistikker

Parallelt med ISteamUserStats findes ISteamGameServerStats for spilservere. Disse kan hente statistikker for brugere på samme måde, som klienter kan (beskrevet ovenfor). De kan også indstille statistikker og prispræstationer, men kun hvis "Sæt med" er sat til "GS" (spilserver) eller "Officiel GS". Forskellen på spilservere og officielle spilservere er, at officielle spilservere er servere, som du hoster og kontrollerer. Brug af officielle spilservere til at indstille statistikker giver øget beskyttelse mod snyd, da brugere muligvis vil kunne modificere deres egne spilservere eller foregive at være en spilserver. For at definere officielle spilservere skal du indtaste IP-intervallet for serverne her.

Statistikker og præstationer, som kan indstilles af spilservere, kan ikke indstilles af klienter. Spilservere kan kun indstille statistikker og præstationer for brugere, som spiller på serveren lige nu. Hvis brugeren forlader serveren, er der en kort frist til at indstille endelige statistikker, men derefter vil nye uploads blive afvist. Dette er for at sikre konsistens og for at undgå at gøre det muligt for en ondsindet spilserver at indstille statistikker på noget tidspunkt. Med denne begrænsning er det vigtigt ikke at vente til udgangen af en runde, før statistikker indstilles. Indstil dem kontinuerligt, så du kan lagrer dem, når en bruger forlader spillet.

Klienter får automatisk opdateringer, når en spilserver ændrer sine statistikker. Men ligesom klienter opdateres statistikker, som indlæses af serveren for andre brugere, ikke automatisk og kan blive forældet.

Nulstilling af statistikker

Under udviklings kan det være nødvendigt helt at nulstille statistikker og præstationer på en konto eller alle konti af hensyn til testformål. For at fjerne statistikker for en konto fuldstændigt skal du kalde ISteamUserStats::ResetAllStats med bAchievementsToo sat til true for også at fjerne præstationer helt. Efter kaldet skal du huske at gentage statistikker og præstationer og nulstille spiltilstanden i hukommelsen. Det er ikke muligt at fjerne statistikker og præstationer globalt for alle brugere. En af grundene til dette er, at selvom alt blev fjernet globalt, risikeres det, at igangværende spil ikke registrerer fjernelsen og indskriver værdier i hukommelsen igen. Det er heldigvis nemt at integrere et globalt nulstillingssystem i dit spil. Sådan gør du:
  • Definer en statistik med et navn, for eksempel "Version"
  • Indsæt et hardcoded statistik-versionsnummer i spillet
  • Når statistikken er indlæst, skal du sammenligne "Version"-statistikken med dit hardcodede versionsnummer
  • Hvis de ikke matcher hinanden, skal du kalde ISteamUserStats::ResetAllStats og derefter sætte "Version"-statistikken til det hardcodede nummer.
På denne måde kan du blot ændre det hardcodede versionsnummer for statistikken for at foretage en global nulstilling. Den globale nulstilling sker, når folk får det nye build.

Statistisk konsistens

Det er en god praksis at tænke på, hvordan relaterede statistikker kan begynde at modsige hinanden. For eksempel hvis du har tre statistikker: "GamesWon", "GamesLost" og "GamesPlayed". På trods af gode intentioner kan og vil statistikker pludselig ikke være synkroniserede. Dette kan medføre, at antallet af vundne og tabte spil tilsammen ikke stemmer med antal spillede spil i alt. Hvis dette blev løst ved at fjerne statistikken "GamesLost" og i stedet beregne den som "GamesPlayed" - "Gameswon", kunne en uoverensstemmelse få "GamesLost" til at være negativ. Her er det bedst at droppe statistikken "GamesPlayed" og beregne det som "GamesWon" + "GamesLost".

Globale statistikker

Statistikken kan markeres som aggregeret på administratorsiden for at give Steam besked om at gemme den samlede værdi for alle brugere. Dette kan bruges til at indhente data om mængden af penge i økonomien, samlet antal drab, yndlingsvåben, yndlingsbaner, og hvilket hold der som regel klarer sig bedst. Modsat bør dette dog ikke bruges for statistikker såsom "MostKills", da det ikke ville give mening at lægge det sammen for flere brugere. Da statistikker er i brugernes hænder, kan dataene manipuleres. Derfor er det afgørende at sætte gode grænser for min. værdi, maks. værdi, kun stigning (hvis relevant) og maks. ændring. Maks. æ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 influere de globale totaler.

For at tilgå de globale totaler skal du kalde ISteamUserStats::RequestGlobalStats og derefter ISteamUserStats::GetGlobalStat for hver globale statistik. Du kan også bede om ISteamUserStats::RequestGlobalStats for et bestemt antal dages historik. Historikken er den mængde, statistikken ændrede sig hver dag. Du kan tilgå historikken med ISteamUserStats::GetGlobalStatHistory.

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

Steam-fællesskabet

Når dit spil er udgivet, vil oplysninger om individuelle og globale præstationsfremskridt blive vist i Steam-fællesskabet. Hver spiller vil have et link fra sin fællesskabsprofil, som går til en side med alt det, spilleren har opnået, og hvad spilleren stadig mangler at oplåse.
BEMÆRK: Præstationer vises ikke, før din app er synlig i en eller anden form i fællesskabet.

Hver præstation vises med det relevante ikon samt navnet og beskrivelsen fra Steamworks-kontrolpanelet. Hvis præstationens navn og beskrivelse er blevet lokaliseret til det sprog, som brugeren har valgt, vil den blive vist på det pågældende sprog.

Der vil også være et link fra denne side og et fra spillets hovedside i Steam til et sæt globale præstationsstatistikker for dit spil. Det viser procenten af Steam-spillere, som har opnået hver præstation, sorteret i rækkefølgen mest almindelige til mest sjældne præstation. Dette er sjovt for spillere at se, og det er også en god resurse for dig som udvikler: Er udfordringerne i dit spil svære nok? Eller måske for svære? (Disse oplysninger kan også tilgås på siden for salg og aktiveringsrapporter).

Flere spørgsmål?

Stil spørgsmål på diskussionssiden for statistikker og præstationer