Leaderboards Service and Leaderboards

Leaderboards Service is responsible for making updates to the player's score in leaderboards for the main game content. It is also used to retrieve leaderboard entries with given parameters. These leaderboard entries can be used to build a leaderboard UI.

Service Default Usage

Leaderboards Service the main method of interfacing with leaderboards is the SetLeaderboardScore(...) method, which uploads the player's provided leaderboard score to the server. In IdleKit the player's score in the main content is tied to the amount of a certain currency the player has earned to date. This currency is defined by the Leaderboard Currency Id" property in the content's data (StandardContentData).

A leaderboard in IdleKit is defined as a piece of content in the leaderboards sheet, and for the main game content the id of the leaderboard that will be used by default is defined in the _leaderboardId field in the StandardContentData. Please note that the _leaderboardId requires for the leaderboard id to be defined in this format: leaderboards.your_leaderboard_id_here.

By default the Leaderboards Service will react to the currency defined by the Leaderboard Currency Id" changing, and save those changes until the next write request is triggered. The server writer request frequency is defined by the LeaderboardUpdateInterval field in the service.

Please note that the service is set up to only react to positive changes in the currency's amount, as the player's score is a cumulative amount of currency the player has earned throughout the event.

So if the player, for example, receives 50 of a certain currency, and their current leaderboard score is 100, because the Leaderboards Service is subscribed to the Currency Changed Action" the Leaderboards service would automatically add the action.Difference parameter (50), to the _currencyDifferenceSinceLastChange field in the service.

The next time the Leaderboards Service writes the leaderboard score to the server, the difference would be added on top of the player's currently existing score. The final result of this call would be that the player's leaderboard score for the current event would be updated to 150, because the increment=TRUE parameter in the SetEventLeaderboardScore(...) makes sure the passed in score is added to the existing leaderboard score.

Projections

Because the player can accumulate points while outside of the game, the Leaderboards Service makes use of the Projection Service to add information about the player's projected score earnings to their recorded leaderboard entry.

This information is written to the dictionary that the SetEventLeaderboardScore(...) accepts, whether or not you have passed in your own optional stats. The service retrieves the player's current projected score in the LeaderboardsTools class in the GetStandardLeaderboardEntryStats method. When retrieving a leaderboard from the Leaderboards Service each leaderboard entry will go through a parsing process in the ConvertLeaderboard(...) method of the LeaderboardsTools class, and as part of that calculate each player's current projected score using IdleKit's Projection Service.

Leaderboard Nicknames/Custom Usernames

Using the Leaderboards Service players will need to set a custom leaderboard username to be displayed in their leaderboard entry. These usernames are NOT unique and need to be set per leaderboard. The IdleKit API does not enforce this directly but a players username will be empty if one is not entered. Your game should force the player to enter a username and/or provide a default one but we leave it up to you to decide how to do that.

To set a players username have your UI pass the leaderboard id and the desired username to the service via SetLeaderboardUsername(leaderboardId, username). When this request is sent it must first pass a profanity filter or it will fail. To fetch an individual players custom leaderboard username you can call GetLeaderboardUsername(leaderboardId, onComplete). Both of these methods call async methods internally. You will not need to call GetLeaderboardUsername(leaderboardId, onComplete) for every player in the leaderboard you want to display - each LeaderboardEntry making up the leaderboard will contain a PlayerNickname property.

Event Leaderboards

Leaderboards for Events are retrieved through the Event Leaderboards Service". Read about it more here: Event Leaderboards

How do I?...

Use something other than currency to determine leaderboard score?

If you wish to decouple the currency amount from the player's leaderboard score, you can inherit from the LeaderboardsService to make your own service, and prevent it from subscribing to the Currency Changed Action". Additionally, you would need to make new helper methods to replace those used in the LeaderboardsTools as existing methods assume that players' offline progression needs to be calculated based on the currency production capabilities of the players' current setup of generators and boosters.