Leaderboards.Client
Like what your seeing?
Support us as a GitHub Sponsor and get instant access to all our assets, exclusive tools and assets, escalated support and issue tracking and our gratitude. These articles are made possible by our GitHub Sponsors ... become a sponsor today!
Introduction
To work with leaderboards from the point of view of a server you should use the Steam Web API for leaderboards.
For more info on how to use the Steamworks Web API please see the Web API Overview.
What can it do?
See the LeaderboardData struct, it can do most everything the raw API can do but is generally easier to work with.
Leaderboards are ranked lists of players where a player's score determines there position on the leaderboard. Leaderboards can contain additional data for each entry either as a details array or as an attachment, attachments are useful for playbacks and other large bits of information while details are useful for character builds, player settings, etc.
Related Objects
Fields and Attributes
RequestTimeout
The amount of time a request will be waited on before it is considered timed out. If a request times out the callback provided will be invoked with a failed IO state i.g.
PendingSetUgcRequests
The number of Set UGC aka AttachUGC requests that are pending processing.
PendingDownloadScoreRequests
The number of download score requests aka DownloadEntries that are pending processing
PendingUploadScoreRequests
The number of upload score requests aka UploadScore that are pending processing
Methods
AttachUGC
The callback deligate should be in the form of
This is used to attach complex data to the user's leaderboard entry. You can do so by providing an existing UGC item or by providing the data to be saved to UGC which will then be attached.
Attaches a piece of user generated content the current user's entry on a leaderboard. 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 accessed by other users using GetDownloadedLeaderboardEntry which contains
LeaderboardEntry_t.m_hUGC
. To create and download user generated content see the documentation for the Steam Workshop. Once attached, the content will be available even if the underlying Cloud file is changed or deleted by the user.
DownloadEntries
The callback deligate should be in the form of
Documentation can be found at the link above.
This is used to query results from a leaderboard and is akin to the DownloadLeaderboardEntries
and DownloadLeaderboardEntriesforUsers
from the raw Steam API.
Fetches a series of leaderboard entries for a specified leaderboard.
You can ask for more entries than exist, then this will return as many as do exist.
A maximum of 100 users can be downloaded at a time, with only one outstanding call at a time. If a user doesn't have an entry on the specified leaderboard, they won't be included in the result.
Find
The callback deligate should be in the form of
The Steamworks Behaviour will call this for you as it initializes the Steam Settings and the boards you have defined within. You only need to call this your self if you are creating a build at run time manually and not using the Leaderboard Object.
GetDisplayType
Gets the display type of the board from Valve's backend.
GetEntryCount
Gets the number of entries recorded on this board
GetName
Gets the name of the leaderboard as recorded on Valve's backend
GetSortMethod
Gets the sorting method used by this board as recorded on Valve's backend.
UploadScore
The callback delegate should be in the form of
Uploads a score and optionally details for the user to the target leaderboard.
Parameters
SteamLeaderboard_t leaderboard
The leaderboard to upload the score toELeaderboardUploadScoreMethod method
The method to upload the score with ... see This Article for full details.int score
The score to be uploadedint[] details
An array of details, this cannot be longer than int[64]. To read the details you must configure the desired length on your Leaderboard Object e.g. in you Steam Settings you must indicate how many detail entries the board's records will have.Action<LeaderboardScoreUploaded_t, bool> callback
A callback that will respond with the result
How To
The Leaderboard object provides simplified access to many of the features found here in. Be sure to read the documentation for the Leaderboard object to understand what options are available to you.
Add an attachment
You can attach files to a user's leaderboard entry using the AttachLeaderboardUGC
option. Attaches a piece of user generated content the current user's entry on a leaderboard. This content could be a replay of the user achieving the score or a ghost to race against.
This requies you have a UGCHandle to the file you wish to attach. See the Remote Storage topic for more information on Shared files.
Alternativly you can pass in a file name and the byte[] date you wish to share, our system will then write that information to the user's remote storage, share it and attach that share handle.
In this case we are writing a file up to the user's remote storage, if that write or the request to share that file should fail then the callback will contain the result code and a value of true on the bool error.
Entries
Entries e.g. the records in the board can be queried in several ways.
Download Entries
Fetches a series of leaderboard entries for a specified leaderboard. You can ask for more entries than exist, then this will return as many as do exist. The request type indicates how the range should be applied, see Valve's documentaiton for more information.
Alternatively you can download the entries for a given set of users. This fetches leaderboard entries for an arbitrary set of users on a specified leaderboard. A maximum of 100 users can be downloaded at a time, with only one outstanding call at a time. If a user doesn't have an entry on the specified leaderboard, they won't be included in the result.
Upload Scores
A user can upload scores and details to a leaderboard at any time. You can control the rules used when uploading scores via the upload method. You can learn more about the upload score method options in Valve's documentation.
Help, my uploaded score doesn't appear!
or
My uploaded score only appears when I use the Force Update option
The most common cause of this is that you have the sort order on your board backwards from what you intend it to be. Please carefully read the documentation on the Sort Method option for Leaderboards.
Also note that once you create a leaderboard with a given sort method it has been observed that it remains with that sort method, and deleting and recreating the board with the same name causes the old sort method to persist. This has to do with how Valve handles the objects in there backend database. The simplest solution is to remove the board, and create a new board with a new name using the proper sorting method.
Last updated