Circuitry Leaderboards

Overview

The Circuitry SDK supports leaderboards that persist along with automatically ordered entries. These leaderboards may be used to display global and friend leaderboards in your application as well as on your community webpage. Each 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 an individual player may have one entry. There is currently no limit on the number of players for each leaderboard. Each entry also contains a score (an int32) and optionally up to 64 int32s of associated data. The data may 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 Circuitry and is replaced when a new leaderboard entry is created for the user.

All leaderboard functions live in the ICircuitryUserGameStats.h file.

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

Creating a Leaderboard

Leaderboards are application specific and are setup on the game setup page of the Robot Cache Partner Portal, or via the API.

The following fields must be completed to define a leaderboard:

  • Name - Set this to be a name that makes sense as part of your development process.
  • Community Name - If the leaderboard is to be shown publically, 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 - This determines the types of data that can be displayed. Options are; Numeric, Seconds or Milliseconds.
  • Writes - If this is set to Trusted, the leaderboard scores cannot be set by users, and can only be set by using the 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 a Leaderboard Using the API

Leaderboards for your game can be created through the Robot Cache Partner Portal or programmatically by calling the ICircuitryUserStats::FindOrCreateLeaderboard function. In Circuitry, all leaderboards for a Circuitry title are identified by a unique name. The leaderboard name is only used for identification in the Circuitry API, and is not presented to users through the Circuitry 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 Robot Cache Partner Portal, you can use the ICircuitryUserStats::FindLeaderboard function to retrieve a handle for your leaderboard. FindLeaderboard and FindOrCreateLeaderboard are asynchronous methods, and return the leaderboard handle for the specified leaderboard through a ICircuitryUserStats::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 ICircuitryUserStats::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 ICircuitryUserStats::UploadLeaderboardScore will replace any data previously stored. You can choose between two update methods when uploading a user's leaderboard score:

  • ICircuitryUserStats::k_ELeaderboardUploadScoreMethodKeepBest - Circuitry 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).
  • ICircuitryUserStats::k_ELeaderboardUploadScoreMethodForceUpdate - Circuitry will always replace the user's score for a leaderboard with the new score.
  • ICircuitryUserStats::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, Circuitry leaderboards are immediately updated to reflect the new score, and the new entry order can be retrieved through DownloadLeaderboardEntries.

Retrieving Leaderboard Entries

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

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

Retrieving Leaderboard Information

You can retrieve information about the leaderboard through the following (assumes you have a leaderboard handle returned from the FindLeaderboard function);

ICircuitryUserStats::GetLeaderboardName
ICircuitryUserStats::GetLeaderboardEntryCount
ICircuitryUserStats::GetLeaderboardSortMethod
ICircuitryUserStats::GetLeaderboardDisplayType