Leaderboards #
Leaderboards are a common feature in games to provide engagement and competitiveness among your player base, and Nakama provides a feature-rich implementation of leaderboards. The Hiro wraps the features and functionality of the Nakama leaderboards system, and adds: built-in support for regional leaderboards, identified by their ISO Code, convenient display for friends leaderboards (using Nakama’s Friends feature), and a convenient way to fan-out score updates to multiple leaderboards.
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 leaderboards system #
The leaderboards system relies on the Nakama System which must be passed in as dependency via the constructor. You can also pass an array of leaderboard Ids for which you would like to retrieve the initial leaderboard records for.
|
|
Subscribing to changes in the leaderboards system #
You can listen for changes in the 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 leaderboards system has the latest information from Nakama you can refresh it.
|
|
You can also refresh an individual leaderboard by passing it’s ID and optionally a cursor.
|
|
Getting leaderboard records #
You can get cached leaderboard records for a specific leaderboard.
|
|
Getting leaderboard records for specific users #
You can get leaderboard records for a specific set of users, by providing either an array of user Ids, a list of friends or a Team (as defined in the TeamNakamaSystem
).
For specific users:
|
|
For friends:
|
|
For the user’s team:
|
|
Getting the user’s own leaderboard record #
You can get the user’s own leaderboard record.
|
|
Submitting a leaderboard score #
You can submit a leaderboard score for the user.
|
|