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 event leaderboard system.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

{
  "event_leaderboards": {
    "leaderboard_id1": {
      "name": "Chef Tournament",
      "description": "Play a tournament against other chefs for great rewards!",
      "category": "Challenges",
      "ascending": false,
      "operator": "best",
      "reset_schedule": "0 0 * * *",
      "cohort_size": 100,
      "additional_properties": {
        "key": "value"
      },
      "max_num_score": 0,
      "reward_tiers": {
        "0": [
          {
            "name": "<tiername>",
            "rank_max": 10,
            "rank_min": 1,
            "reward": {
              "guaranteed": {
                "currencies": {
                  "coins": {
                    "min": 1000,
                    "max": 2000
                  }
                }
              }
            },
            "tier_change": 1
          },
          {
            "name": "<tiername2>",
            "rank_max": 90,
            "rank_min": 11,
            "reward": {},
            "tier_change": 0
          },
          {
            "name": "<tiername3>",
            "rank_max": 100,
            "rank_min": 91,
            "reward": {},
            "tier_change": -1
          }
        ]
      },
      "change_zones": {
        "0": {
          "promotion": 0.5,
          "demotion": 0,
          "demote_idle": false
        },
        "1": {
          "promotion": 0.2,
          "demotion": 0.3,
          "demote_idle": true
        }
      },
      "tiers": 5,
      "max_idle_tier_drop": 1,
      "start_time_sec": 0,
      "end_time_sec": 0,
      "duration": 86400
    }
  }
}

The JSON schema defines an event_leaderboards object which must contain an individual object for each event leaderboard you wish to define in the system. You can configure as few or as many event leaderboards as needed for your game.

Each individual event leaderboard is keyed by id and may define the following:

Event Leaderboard #

Reward Tier #

Change Zone #