Event Leaderboards Service

Event Leaderboards Service is based on the Leaderboards Service and is responsible for making updates to the player's score in the event leaderboards. It is also used to retrieve event leaderboard entries with given parameters. These leaderboard entries can be used to build a leaderboard UI.

Service Default Usage

Event Leaderboards Service the main method of interfacing with event leaderboards is the SetEventLeaderboardScore(...) method, which uploads the player's provided leaderboard score to the server. In IdleKit the player's score in an event 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 event's content data (StandardEventContentData).

While a main content leaderboard in IdleKit is defined as a piece of content in the leaderboards sheet, the event leaderboards are generated and linked to the event content automatically in the backend. This means that the _leaderboardId field in the StandardEventContentData is unused.

By default the Event Leaderboards Service will react to the currency defined by the LeaderboardCurrencyId 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 Event Leaderboards Service is subscribed to the Currency Changed Action the Event Leaderboards service would automatically add the action.Difference parameter (50), to the _currencyDifferenceSinceLastChange field in the service.

The next time the Event 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 event 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 leaderboard score while outside of an event, the Event Leaderboards Service makes use of the Projection Service to add information about the player's projected final and ongoing scores in the event to their leaderboard entry.

This information is written to the optional dictionary that the SetEventLeaderboardScore(...) method accepts, whether or not you have passed in your own optional stats. The service retrieves the player's current projected score by the end of the event and their payout projections from the Projection Service. These projected scores are calculated based on the player's currently automated generators and their payout rates. By saving the resulting values in the leaderboard's optional parameters with keys _final_score and projections we are able to determine the player's final and ongoing offline score later on, even if the player is absent from the event for a long time, and only comes back to the game once the event has ended.

Additionally, our backend system - Beamable - uses the _final_score to automatically set this value as the player's final score when the event ends.

Leaderboard Nicknames/Custom Usernames

Nicknames are handled the same in events as global leaderboards, for more info see Leaderboards Service.

How do I?...

Use something other than currency to determine event leaderboard score?

If you wish to decouple the currency amount from the player's event leaderboard score, you can inherit from the EventLeaderboardsService to make your own service, and prevent it from subscribing to the Currency Changed Action".

Request a friends leaderboard for an event outside of it?

If you wish to request a friends leaderboard for an event, while currently being outside of the event, you will need to use the GetFriendsLeaderboard(...) method from Leaderboards Service directly.