Event Leaderboards #
Event leaderboards are a high-level feature of Hiro, built on top of the Nakama leaderboards feature, that enable you to add timed and scored events, which are a great way to add competitive elements to your game. These events can optionally have an associated cost to participate.
Timed event leaderboards allow users to play against a bucket of opponents for the duration of the event. This bucket of opponents is generated on request and the duration is configured via a CRON expression. At the end of the event rewards are distributed based on a range of ranks.
Scored event leaderboards allow users to play against a bucket of opponents and “race” towards a defined target score. If the target score is achieved within the defined range of rewards, the user is a winner.
When the range of ranks for rewards is achieved by the specified number of users, the opponents for all of those users can be “rerolled”. The rerolled opponents can be played again to race for rewards. This can happen up to a maximum number of configurable rerolls. At the end of the duration of the event no more rerolls can be made and the event ends.
For both types of event the bucket of opponents generated for each user is individual to that user and can be specified up to a maximum of 100 players.
Customization parameters #
The following JSON represents the customization parameters you can use to configure the default user experience for the leaderboard system.
|
|
The JSON schema defines an events
object which must contain an individual object for each leaderboard you wish to define in the system. You can configure as few or as many energy types as needed for your desired gameplay.
Each leaderboard is keyed by id and may define the following:
Property | Subproperty | Description |
---|---|---|
name | The name of this leaderboard. | |
description | The description of this leaderboard. | |
operator | The leaderboard operation (e.g. set , best , incr , or decr ). | |
sort | The leaderboard sort type (e.g. asc or desc ). | |
start_time | The start time (as a UNIX timestamp) of this leaderboard. | |
end_time | The end time (as a UNIX timestamp) of this leaderboard. | |
reset | The reset schedule of this leaderboard expressed as a CRON expression. | |
score_target | An optional score target a user must reach for the leaderboard event to be considered won. | |
max_reroll_count | The maximum amount of times a user can reroll their score. | |
bucket_size | The size of the bucket of users when using bucketed leaderboards. | |
resource_id | A string hint for the client (e.g. addressable field). | |
cost | An object that defines the entry cost for this leaderboard. | |
currencies | A string:int dictionary of currencies and quantities the user should receive as a reward. | |
reward_ranges | An array of objects that define the various rewards available to players based on their final rank in the leaderboard. | |
rank_start | The first rank included in the reward range. | |
rank_end | The last rank included in the reward range. | |
reward | An object that defines what rewards the players will receive. See schema below for properties. | |
reward_ranges_team | An array of objects that define the various rewards available to players who participate in a team based on the team’s final rank in the leaderboard. | |
rank_start | The first rank included in the reward range. | |
rank_end | The last rank included in the reward range. | |
reward | An object that defines what rewards the players will receive. See schema below for properties. |
The rewards properties above (reward_ranges
, reward_ranges_team
) have the additional sub-properties:
Property | Description |
---|---|
currencies | A string:int dictionary of currencies and quantities the user will receive for the given rank range. |
Initializing the event leaderboards system #
The event leaderboards system relies on the Nakama System which must be passed in as dependency via the constructor. You can also pass an array of event leaderboard Ids for which you would like to retrieve the initial leaderboard records for.
|
|
Subscribing to changes in the event leaderboards system #
You can listen for changes in the event leaderboards system so that you can respond appropriately, such as updating the UI, by implementing the appropriate interface.
|
|
Refreshing the leaderboards system #
To ensure the event leaderboards system has the latest information from Nakama you can refresh it.
|
|
You can also refresh an individual event leaderboard by passing it’s ID and optionally a cursor.
|
|
Listing event leaderboards #
You can list all event leaderboards for the user.
|
|
Getting an individual event leaderboard #
You can get an individual event leaderboard, including it’s records and information on it’s rewards.
|
|
Submitting an event leaderboard score #
You can submit an event leaderboard score for the user.
|
|
Claiming rewards #
You can claim event leaderboard rewards for the user.
|
|
Joining or re-rolling an event leaderboard #
You can join or re-roll an event leaderboard as a user. A re-roll would occur when a user has previously joined an event leaderboard and claimed their reward but would now like to re-join again for another chance at claiming a reward.
|
|