Documentazione di Steamworks
Steam Leaderboards

Panoramica

Steam supporta la creazione di classifiche persistenti con voci ordinate automaticamente. Le classifiche possono essere utilizzate per mostrare il punteggio degli amici e degli utenti di tutto il mondo all'interno del gioco e sulla pagina web della Comunità. Per ogni titolo di Steamworks possono essere create fino a 10.000 classifiche, ognuna delle quali può essere recuperata subito dopo l'inserimento del punteggio di un giocatore.

For each leaderboard, a player can have one entry. Non c'è limite al numero di giocatori che possono entrare nelle classifiche. Ciascuna voce contiene il punteggio per la classifica di riferimento (un valore int32) e, facoltativamente, fino a 64 valori int32 dei dati associati. I dati associati possono essere utilizzati per conservare informazioni specifiche sulla sessione di gioco che ha portato l'utente a entrare in classifica. Questi dati non vengono ordinati né analizzati da Steam, e vengono sostituiti alla creazione di una nuova voce della classifica per l'utente.

Tutte le funzioni delle classifiche sono incluse in ISteamUserGameStats.h. Due classifiche esemplificative sono state implementate nell'esempio di Steamworks. Puoi visualizzare e gestire le classifiche del tuo gioco anche dalla pagina Amministratore gioco su Steamworks.

Cenni preliminari

Tutte le funzioni asincrone delle classifiche restituiscono un handle al risultato della chiamata all'API di Steam. You can find more information on how to receive these results from the Call Result section of the Getting Started document.

Creazione di una classifica

Leaderboards are application specific and are setup on the Game Admin page of the Steamworks partner site, or via the API.

Creazione tramite il web

You can create and manage leaderboards in the Steamworks App Admin for your app ID by going to Stats & Achievements -> Leaderboards.
spacewar_leaderboards

Per definire una classifica è necessario compilare i campi di seguito:
  • Name - Set this to be a name that makes sense as part of internal development.
  • Community Name - If the leaderboard is to be shown on the Community Hub, set the public facing name here. If there is no name entered, the leaderboard will not appear.
  • Sort Method - Set the order for the leaderboard sorting. For positional based leaderboards, use Ascending. For high-score, use Descending.
  • Display Type - Determines the types of data to be displayed with the leaderboard. Select from Numeric, Seconds or Milliseconds.
  • Writes - If this is set to Trusted, the leaderboard scores cannot be set by clients, and can only be set by via SetLeaderboardScore WebAPI. Defaults to false.
  • Reads - If this is set to Friends, the game can only read leaderboard scores for friends of the user, all scores can always be read by WebAPI. Defaults to false.

Creating via the API

Leaderboards for your game can be created through the Steamworks App Admin or programmatically by calling ISteamUserStats::FindOrCreateLeaderboard. In Steam, all leaderboards for a Steamworks title are identified by a unique name. The leaderboard name is only used for identification in the Steamworks API, and is not presented to users through the Steam Community. When creating a leaderboard, you will need to choose a:

  • sort method - k_ELeaderboardSortMethodAscending (the top entry is the user with the lowest score) or k_ELeaderboardSortMethodDescending (the top entry is user with the highest score)
  • display type - ELeaderboardDisplayType is used to describe what a leaderboard score represents, and is only used by the community to format leaderboard scores when displayed

If you choose to only create your leaderboards through the App Admin, you can use ISteamUserStats::FindLeaderboard to retrieve a handle for your leaderboard. FindLeaderboard and FindOrCreateLeaderboard are asynchronous methods, and return the leaderboard handle for the specified leaderboard through a ISteamUserStats::LeaderboardFindResult_t call result.

Once a leaderboard has been created, you can modify the sort method and display type for a leaderboard through the Game Admin. When FindOrCreateLeaderboard is called for an existing leaderboard, the sort method and display type parameters are ignored.
NOTE: If the leaderboard is to be shown on the Community Hub, you must set the Community Name field when defining the leaderboard. If there is no name entered, the leaderboard will not appear.

Uploading a Score

To upload a leaderboard score, simply call ISteamUserStats::UploadLeaderboardScore passing the target leaderboard's handle (retrieved through FindLeaderboard), the user's score and optionally any associated data generated when setting the new score. If the user's leaderboard score is updated, the associated data passed to ISteamUserStats::UploadLeaderboardScore will replace any data previously stored. You can choose between two update methods when uploading a user's leaderboard score:

  • ISteamUserStats::k_ELeaderboardUploadScoreMethodKeepBest - Steam will compare the user's new score with his score already stored in the leaderboard, and keep the user's best score (the lowest score for leaderboards with an ascending sort order; the highest score for leaderboards with a descending sort order).
  • ISteamUserStats::k_ELeaderboardUploadScoreMethodForceUpdate - Steam will always replace the user's score for a leaderboard with the new score.
  • ISteamUserStats::UploadLeaderboardScore is an asynchronous call, and the result of the upload is returned in a LeaderboardScoreUploaded_t call result. The result contains a flag marking if the user's score has changed, and the user's old and new global rank. Once uploaded, Steamworks leaderboards are immediately updated to reflect the new score, and the new entry order can be retrieved through DownloadLeaderboardEntries.

Attaching User Generated Content

After a score has been uploaded you have the option to attach user generated content for the entry. To do so, simply call ISteamUserStats::AttachLeaderboardUGC This content could be a replay of the user achieving the score or a ghost to race against. The attached handle will be available when the entry is retrieved and can be downloaded by other users. To create and download user generated content see the documentation for Steam Cloud.

Once attached, the content will be available even if the underlying Cloud file is changed or deleted by the user.

Retrieving Leaderboard Entries

ISteamUserStats::DownloadLeaderboardEntries is used to retrieve leaderboard entries using the leaderboard handle retrieved through ISteamUserStats::FindLeaderboard.

Once you have retrieved all downloaded entries from GetDownloadedLeaderboardEntry, the entry data will be freed and the SteamLeaderboardEntries_t in LeaderboardScoresDownloaded_t will no longer be valid.

Retrieving Leaderboard Information

With a leaderboard handle returned from FindLeaderboard, you can retrieve information about the leaderboard through the following:

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