Oversigt

Steam understøtter vedvarende førertavler med automatisk sorterede poster. Disse førertavler kan bruges til at vise globale og venneførertavler i dit spil og på din fællesskabsside. Hver Steamworks-titel kan oprette op til 10.000 førertavler, og hver førertavle kan hentes umiddelbart efter, at en spillers score er blevet indtastet.

En spiller kan have én position på hver førertavle. Der er ingen grænse for, hvor mange spillere der kan være pr. førertavle. Hver position på førertavlen indeholder en score (en int32) og op til 64 int32'ere med tilknyttede data. De tilknyttede data kan bruges til at lagre spilspecifikke oplysninger om spilsessionen, der resulterede i brugerens førertavleposition. Disse data sorteres eller fortolkes ikke af Steam og erstattes, når der oprettes en ny førertavleposition for brugeren.

Alle førertavlefunktioner ligger i ISteamUserGameStats.h, og der er implementeret to førertavleeksempler i Steamworks-eksemplet. Det er også muligt at se og administrere førertavler for dit spil i spiladministratoren i Steamworks.

Inden du begynder

Alle asynkrone førertavlefunktioner returnerer et handle til et Steam-API-opkaldsresultat. Du kan finde mere information om, hvordan disse resultater modtages, i sektionen "Kaldsresultat" i dokumentet "Sådan kommer du i gang".

Opret en førertavle

Førertavler er applikationsspecifikke og konfigureres på siden "Spiladministrator" på Steamworks-partnersiden eller via API'en.

Oprettelse via web

Du kan oprette og administrere førertavler i "App-administrator" i Steamworks for dit app-ID ved at gå til Statistikker og præstationer -> Førertavler.


Følgende felter skal udfyldes for at definere en førertavle:

• Navn: Dette skal være et navn, som giver mening i forhold til intern udvikling.
  
• Fællesskabsnavn: Angiv et offentligt navn her, hvis førertavlen skal vises i fællesskabshubben. Hvis der ikke angives et navn, vises førertavlen ikke.
  
• Sorteringsmetode: Angiv sorteringsrækkefølgen for førertavlen. Vælg "Stigende" for positionsbaserede førertavler. Vælg "Faldende" for rekorder.
  
• Visningstype: Fastsætter de typer af data, der vises med førertavlen. Vælg mellem "Numerisk", "Sekunder" eller "Millisekunder".
  
• Skriver: Hvis dette er sat til "Pålidelig" (Trusted), kan klienter ikke indstille førertavlescores – det kan kun gøres via web-API'en SetLeaderboardScore. Standardindstilling er false.
  
• Læser: Hvis dette er sat til "Venner", kan spillet kun læse førertavlescores for brugerens venner – alle scores kan altid læses af WebAPI. Standardindstilling er false.

Oprettelse via API'en

Du kan oprette førertavler for dit spil via "App-administrator" i Steamworks eller programmatisk ved at kalde ISteamUserStats::FindOrCreateLeaderboard. I Steam identificeres alle førertavle for en Steamworks-titel med et unikt navn. Navnet på førertavlen bruges kun til identifikation i Steamworks-API'en og vises ikke for brugere via Steam-fællesskabet. Når du opretter en førertavle, skal du vælge en:

• sorteringsmetode – k_ELeaderboardSortMethodAscending (den øverste position er den bruger, der har den laveste score) eller k_ELeaderboardSortMethodDescending (den øverste position er den bruger, der har den højeste score)
  
• visningstype – ELeaderboardDisplayType bruges til at beskrive, hvad scoren på førertavlen repræsenterer og bruges kun af fællesskabet til at formatere førertavlescoren, når den vises

Hvis du vælger kun at oprette dine førertavler via App-administrator, kan du bruge ISteamUserStats::FindLeaderboard til at hente et handle for din førertavle. FindLeaderboard og FindOrCreateLeaderboard er asynkrone metoder og returnerer et førertavle-handle for den angivne førertavle via et ISteamUserStats::LeaderboardFindResult_t-kaldsresultat.

Når der er oprettet en førertavle, kan du ændre sorteringsmetoden og visningstypen for førertavlen via spiladministratoren. Når FindOrCreateLeaderboard kaldes for en eksisterende førertavle, ignoreres sorteringsmetode- og visningstypeparametrene.

Upload en score

For at uploade en førertavlescore skal du blot kalde ISteamUserStats::UploadLeaderboardScore og passere målførertavlens handle (hentes via FindLeaderboard), brugerens score og evt. tilknyttede data, som genereres, når den nye score angives. Hvis brugerens førertavlescore opdateres, vil de tilknyttede data, som sendes til ISteamUserStats::UploadLeaderboardScore, erstatte tidligere data. Du kan vælge mellem to opdateringsmetoder, når en brugers førertavlescore uploades:

• ISteamUserStats::k_ELeaderboardUploadScoreMethodKeepBest – Steam sammenligner brugerens nye score med den score, der allerede er lagret for brugeren på førertavlen, og beholder brugerens bedste score (den laveste score for førertavler med stigende sorteringsrækkefølge, den højeste score for førertavler med faldende sorteringsrækkefølge).
  
• ISteamUserStats::k_ELeaderboardUploadScoreMethodForceUpdate – Steam erstatter altid brugerens score til førertavlen med den nye score.
  
• ISteamUserStats::UploadLeaderboardScore er et asynkront kald, og uploadresultatet returneres i et LeaderboardScoreUploaded_t-kaldsresultat. Resultatet indeholder et flag, som markerer, om brugerens score er ændret, og brugerens gamle og nye globale rang. Når scoren er uploadet, opdateres Steamworks-førertavlerne med det samme, så de viser den nye score, og den nye positionsrækkefølge kan hentes via DownloadLeaderboardEntries.

Vedhæft brugerskabt indhold

Når en score er blevet uploadet, kan du vedhæfte brugerskabt indhold for positionen. For at gøre dette skal du blot kalde ISteamUserStats::AttachLeaderboardUGC. Dette kan være en gengivelse af det øjeblik, hvor brugeren opnår scoren, eller et spøgelse at kæmpe imod. Det vedhæftede handle vil være tilgængeligt, når positionen hentes og kan downloades af andre brugere. Se dokumentationen om Steam Cloud for at læse om at oprette og downloade brugerskabt indhold.

Når indholdet er vedhæftet, er det tilgængeligt, selvom den underliggende Cloud-fil ændres eller slettes af brugeren.

Hent positioner på førertavler

ISteamUserStats::DownloadLeaderboardEntries bruges til at hente førertavlepositioner med det førertavle-handle, der hentes via ISteamUserStats::FindLeaderboard.

Når du har hentet alle downloadede positioner fra GetDownloadedLeaderboardEntry, frigives positionsdataene, og SteamLeaderboardEntries_t i LeaderboardScoresDownloaded_t er ikke længere gyldig.

Hent oplysninger om førertavler

Når et førertavle-handle returneres fra FindLeaderboard, kan du hente oplysningerne om førertavlen ved hjælp af følgende:

ISteamUserStats::GetLeaderboardName
ISteamUserStats::GetLeaderboardEntryCount
ISteamUserStats::GetLeaderboardSortMethod
ISteamUserStats::GetLeaderboardDisplayType