Overview

Steam supports persistent leaderboards with automatically ordered entries. These leaderboards can be used to display global and friend leaderboards in your game and on your community webpage. Each Steamworks title can create up to 10,000 leaderboards, and each leaderboard can be retrieved immediately after a player's score has been inserted.

For each leaderboard, a player can have one entry. There is no limit on the number of players per leaderboard. Each entry contains a score for the leaderboard (an int32) and optionally up to 64 int32s of associated data. The associated data can be used to store game specific information about the play session that resulted in the user's leaderboard entry. This data is not sorted or parsed by Steam, and is replaced when a new leaderboard entry is created for the user.

All leaderboard functions live in ISteamUserGameStats.h, and two sample leaderboards have been implemented in the Steamworks example. It is also possible to view and administer leaderboards for your game in the Steamworks Game Admin.

Before You Begin

All asynchronous leaderboard functions return a handle to a Steam API call result. You can find more information on how to receive these results from the Call Result section of the Getting Started document.

Creating a Leaderboard

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

Creating via the Web

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


The following fields must be completed to define a leaderboard:

• 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.

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