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 event leaderboard. | |
description | The description for this event leaderboard. | |
category | The category for this event leaderboard. | |
operator | The leaderboard operation (e.g. set , best , incr , or decr ). | |
ascending | Whether the records are sorted in Ascending order or not. | |
reset_schedule | The reset schedule of this leaderboard expressed as a CRON expression. | |
cohort_size | The size of the cohort that participants will be grouped into. | |
additional_properties | A string:string dictionary of key value pairs that can contain additional context. | |
max_num_score | The maximum amount of scores a user can submit per reset. | |
tiers | The number of tiers that users can progress through. | |
max_idle_tier_drop | The maximum number of tiers an idle player can be demoted. | |
start_time_sec | The start time (as a UNIX timestamp) of this event leaderboard. | |
end_time_sec | The end time (as a UNIX timestamp) of this event leaderboard. | |
duration | The duration in seconds for the event leaderboard active period. | |
change_zones | A map that defines the promotion and demotion zones per tier, keyed by tier as a string. | |
promotion | The percentage (as a number between 0 and 1) of players at the top of the cohort who will be promoted. | |
demotion | The percentage (as a number between 0 and 1) of players at the bottom of the cohort who will be demoted. | |
demote_idle | Whether or not idle players in the cohort should be automatically demoted. | |
reward_tiers | A map that defines the various rewards (as an array) per tier, keyed by tier as a string. | |
rank_min | The minimum rank number (inclusive) eligible for this reward. | |
rank_max | The maximum rank number (inclusive) eligible for this reward. | |
tier_change | Optionally defines a change in tier the player should receive for getting this reward. | |
reward | A reward object that defines the reward the player should receive. |