Event Leaderboards

Event Leaderboards enable fair and structured competitive events that run alongside your core gameplay. Unlike standard leaderboards where new players might end up competing against veterans, Event Leaderboards place each player into a small cohort of similarly-skilled opponents, giving everyone a realistic chance to win. The system handles scheduling, matchmaking, reward distribution, and tier progression automatically.

Event Leaderboards support two types of competition:

• Time-based events: Players compete for rankings within a fixed time window. The cohort ends when the timer expires. This suits weekly tournaments, seasonal competitions, and league systems.
• Score-based events: Players race to reach a target score. The cohort completes when enough players hit the target. Players can then claim rewards and immediately roll into a new cohort for another round. This enables fast-paced, repeatable competitive loops within a single event phase.

Both types can be combined with tiers (e.g. Bronze, Silver, Gold leagues) to create long-term progression systems.

Key terms #

Phase #

A phase is a single cycle within an Event Leaderboard, governed by the event’s schedule (e.g. a daily reset, a weekly reset, or a fixed start/end time). Each phase gives players a fresh window to compete.

In time-based events, a phase typically contains a single competition: players join a cohort, compete until the timer expires, and claim rewards. In score-based events, a single phase can contain multiple rounds of competition where players complete a cohort, claim rewards, and re-roll into a new cohort, all within the same phase. See Multi-stage challenge for an example.

When a new phase begins, all roll counts reset and players start fresh.

Roll #

A roll is the act of joining a cohort within the current phase. When a player rolls, they are assigned to a cohort of opponents at their tier level and can begin submitting scores.

The first roll in a phase places the player into a cohort for the first time. Any subsequent roll within the same phase is a re-roll.

Re-roll #

Re-rolling happens when a player leaves a cohort and joins a fresh one with new opponents, all within the same active phase.

Re-rolling is only possible when all of the following are true:

1. The player’s current cohort is complete, whether individually or for the entire cohort.
2. The player has claimed their reward from the current cohort.
3. The player has remaining rolls (that is, their roll count has not reached max_rolls).
4. Any applicable roll cooldown (roll_cooldown_sec) has elapsed.
5. The phase has not expired.

When a player re-rolls, their score from the previous cohort is preserved so other players in that cohort can still see it. The player then starts with a clean slate in the new cohort. See Ending a cohort.

Reroll count freeze #

Reroll count freeze controls whether a roll counts against the player’s max_rolls limit. When frozen, the roll is “free” and the player’s roll count does not increment.

This can be configured based on two outcomes:

Based on tier change (in change zones):

• promotion_reroll_count_freeze: free roll if the player is promoted to a higher tier
• demotion_reroll_count_freeze: free roll if the player is demoted to a lower tier
• nochange_reroll_count_freeze: free roll if the player stays in the same tier

Based on reward placement (in reward tiers):

• reroll_count_freeze: free roll if the player finishes in this reward bracket

This mechanic is useful for encouraging specific behaviors. For example, making promotions “free” means players who are climbing through tiers can keep playing without burning through their roll limit.

Controlling re-rolls with max_rolls #

max_rolls is the maximum number of times a player can roll (join a cohort) within a single phase. It is the primary control for whether an event allows re-rolling, and effectively determines what type of event you are running.

Each player’s roll count (the number of times they have rolled within the current phase) resets to 0 at the start of each new phase.

Cohort #

A cohort is a group of players competing against each other on a shared leaderboard. Each cohort contains up to cohort_size players and exists within the context of a single phase.

How players are assigned to cohorts #

When a player rolls, the system determines their current tier and finds them a cohort:

1. Tier determination: New players start at tier 0. Returning players have their tier calculated based on previous performance using change zones or reward tier rules.
2. Tier matching: The system looks for cohorts at the player’s current tier level.
3. First-come-first-served: Within the tier, players are assigned to existing cohorts that have available slots.
4. New cohort creation: If no suitable cohort has space, a new one is created.
5. Re-roll exclusion: When re-rolling, the system excludes cohorts the player has already been part of, ensuring they always face new opponents.

Custom matchmaking: You can implement custom cohort selection logic through the SetOnEventLeaderboardCohortSelection callback for more sophisticated matching (e.g. skill-based matching beyond tiers, custom cohort assignments, or forced new cohort creation).

Cohort behavior in time-based events #

In time-based events, cohorts follow a straightforward lifecycle:

• The cohort starts when players are assigned and ends when the phase timer expires
• All players compete for the full duration of the phase
• No early completion is possible
• Re-rolling within the phase is not practical, since the cohort only ends when the phase ends

Cohort behavior in score-based events #

In score-based events, cohorts can complete before the phase timer expires:

• A player’s cohort can complete when they reach the score_target
• Individual players can complete their cohort independently
• When enough players reach the target to fill all reward slots, the entire cohort locks and no new players can join it, since the results are already determined
• The phase timer still acts as an ultimate deadline

Ending a cohort #

A cohort ends when any of the following conditions are met. Which conditions apply depends on which configuration fields are set:

• Phase expires: The phase timer runs out. This always applies regardless of other settings.
• Player hits score target: If score_target is configured, a player’s cohort completes for them individually when they reach the target score. Everyone else may remain in the cohort.
• Score target saturation: If both score_target and score_target_players are configured, the cohort completes everyone when that many players reach the target. No new players can be assigned to a completed cohort.
• All players timed out: If score_time_limit_sec is configured and the cohort is full, the cohort completes when every player’s individual time limit has expired.
• All attempts exhausted: If max_num_score is configured and the cohort is full, the cohort completes when every player has used all their score submissions.

These conditions are independent. When multiple are configured, whichever triggers first wins. Once a cohort is complete for a player, they can claim rewards but can no longer submit scores.

Claim #

Claiming is the act of collecting rewards from a completed cohort. A player can claim when their cohort is complete and they haven’t already claimed.

For convenience, the roll endpoint accepts a claimReward parameter that claims the current reward and rolls into a new cohort in a single call. This is the recommended approach for re-rolling, as it reduces round-trips and avoids the player needing to manually claim before rolling. See the Unity SDK guide for usage examples.

Rewards #

Rewards are prizes distributed to players based on their final ranking within a cohort. Each Event Leaderboard defines one or more reward tiers — rank-based brackets that map finishing positions to prizes. For example, an Event Leaderboard might define three reward tiers: ranks 1–3 receive a “Gold-tier” reward, ranks 4–10 receive a “Silver-tier” reward, and ranks 11–20 receive a “Bronze-tier” prize. Each reward tier can also trigger a tier promotion or demotion (see Tiers below). For more details on reward contents, see Rewards.

Tiers #

Tiers represent skill or progression levels that persist across phases. Players can move up or down tiers based on their performance, creating long-term progression beyond individual events. Common examples include league systems that see players progress from “Bronze III” to “Grandmaster I” over the course of several seasons. Players always start at the lowest tier and cannot drop below it or exceed the maximum configured tier.

Change zones #

Change zones define the promotion and demotion rules for each tier. A change zone specifies what percentage of top performers advance to a higher tier and what percentage of bottom performers drop down. These can be configured differently per tier to create varied competitive dynamics.

Time-based events #

In time-based events, players join a cohort, compete for the highest score over a fixed time window, and claim rewards when the timer expires. Use this for weekly tournaments, seasonal events, ranked leagues, or any competition where all players compete over the same duration.

General flow:

1. Player rolls into a cohort at the start of the phase
2. Player submits scores throughout the phase
3. Phase timer expires, completing the cohort for everyone
4. Player claims rewards based on final ranking
5. Next phase begins

Key characteristics:

• Cohorts always run for the full phase duration
• All players in a cohort experience the same start and end

Example: Weekly tournament #

This is the simplest Event Leaderboard pattern and works well for any game with a core gameplay loop that produces scores. The recurring schedule creates a natural reason for players to return each week.

How it works: Every Monday a new phase begins. Players are placed into cohorts of 50 and compete for the highest score over 7 days. When the phase ends on Sunday, rewards are distributed based on final rankings. A new phase begins the following Monday.

Example configuration

 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

{
  "event_leaderboards": {
    "weekly_tournament": {
      "name": "Weekly Tournament",
      "description": "Compete for the highest score this week!",
      "category": "competitive",
      "ascending": false,
      "operator": "best", // Only each player's highest score counts
      "reset_schedule": "0 0 * * 1", // Resets every Monday at midnight UTC
      "cohort_size": 50,
      "max_num_score": 0, // No limit on score submissions
      "tiers": 1, // There is no progression in this event, so there is only one tier
      "max_idle_tier_drop": 0,
      "start_time_sec": 0,
      "end_time_sec": 0,
      "duration": 604800, // 7 days in seconds
      "reward_tiers": {
        "0": [
          {
            "name": "Gold",
            "rank_min": 1,
            "rank_max": 5,
            "tier_change": 0,
            "reward": {
              "guaranteed": {
                "currencies": {
                  "coins": { "min": 5000, "max": 5000 }
                }
              }
            }
          },
          {
            "name": "Silver",
            "rank_min": 6,
            "rank_max": 25,
            "tier_change": 0,
            "reward": {
              "guaranteed": {
                "currencies": {
                  "coins": { "min": 2000, "max": 2000 }
                }
              }
            }
          },
          {
            "name": "Bronze",
            "rank_min": 26,
            "rank_max": 50,
            "tier_change": 0,
            "reward": {
              "guaranteed": {
                "currencies": {
                  "coins": { "min": 500, "max": 500 }
                }
              }
            }
          }
        ]
      }
    }
  }
}

Score-based events #

In score-based events, players race to reach a target score. Once the target is hit, the cohort completes for that player, even if the phase timer hasn’t expired yet. Combined with max_rolls > 1, this enables a loop where players compete, finish a cohort, claim their reward, and then roll into a new cohort, all within a single phase.

Use this for race-to-the-finish challenges, multi-round competitions, and events where players can win and play again for more rewards.

General flow:

1. Player rolls into a cohort
2. Player submits scores, racing toward the score_target
3. Player (or enough players) hits the target, completing the cohort
4. Player claims rewards
5. If rolls remain, player rolls into a new cohort with new opponents
6. Repeat until out of rolls or the phase expires

Key characteristics:

• Cohorts can complete before the phase timer expires
• Players can participate in multiple cohorts within a single phase
• max_rolls is set higher than 1 to enable re-rolling
• score_target defines the completion threshold

Example: Race-to-the-finish #

Players race to reach a target score before their opponents. The first players to hit the target win rewards, and once the race is over, everyone can immediately roll into a new cohort for another round. Change zones promote top performers and demote those in last place. This type of Event Leaderboard is used in many popular games, such as Sky Race from Royal Match.

How it works: A weekend event runs Friday through Monday. Players are grouped into small cohorts of 5 and race to complete 15 levels (represented as a score target of 15). The first 3 players to finish claim rewards. After a race ends, all players can immediately join a new race with fresh opponents. There is no limit on races per phase. At the end of each phase, change zones determine who moves up or down across 5 tiers (Bronze through Diamond).

Example configuration

 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
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

{
  "event_leaderboards": {
    "speed_race": {
      "name": "Speed Race",
      "description": "Race to the finish! Beat 15 levels before your opponents.",
      "category": "competitive",
      "ascending": false,
      "operator": "incr", // Client sends 1 per level cleared, score increments toward target
      "reset_schedule": "0 12 * * 5", // New phase every Friday at noon UTC
      "cohort_size": 5,
      "max_num_score": 0, // No limit on score submissions
      "tiers": 5, // 5 leagues: Bronze → Silver → Gold → Platinum → Diamond
      "max_idle_tier_drop": 1, // Idle players drop 1 tier per phase
      "start_time_sec": 0,
      "end_time_sec": 0,
      "duration": 259200, // 3 days (Friday–Monday)
      "max_rolls": 9999, // Effectively unlimited races per phase
      "score_target": 15, // Race completes when a player reaches 15
      "score_target_players": 3, // Cohort completes once 3 of 5 players finish (aligns with reward ranks 1-3)
      "roll_cooldown_sec": 0, // Players can immediately re-roll after claiming
      "reward_tiers": {
        "0": [
          {
            "name": "Gold",
            "rank_min": 1,
            "rank_max": 1,
            "tier_change": 0,
            "reward": {
              "guaranteed": {
                "currencies": {
                  "coins": { "min": 1000, "max": 1000 }
                }
              }
            }
          },
          {
            "name": "Silver",
            "rank_min": 2,
            "rank_max": 2,
            "tier_change": 0,
            "reward": {
              "guaranteed": {
                "currencies": {
                  "coins": { "min": 100, "max": 100 }
                }
              }
            }
          },
          {
            "name": "Bronze",
            "rank_min": 3,
            "rank_max": 3,
            "tier_change": 0,
            "reward": {
              "guaranteed": {
                "currencies": {
                  "coins": { "min": 10, "max": 10 }
                }
              }
            }
          }
        ]
      },
      "change_zones": {
        "0": {
          // Bronze: generous promotion, no demotion (already lowest tier)
          "promotion": 0.6,
          "demotion": 0,
          "demote_idle": false
        },
        "1": {
          // Silver: moderate promotion, light demotion
          "promotion": 0.4,
          "demotion": 0.2,
          "demote_idle": true
        },
        "2": {
          // Gold: moderate promotion, light demotion
          "promotion": 0.4,
          "demotion": 0.2,
          "demote_idle": true
        },
        "3": {
          // Platinum: tough promotion, heavier demotion
          "promotion": 0.2,
          "demotion": 0.4,
          "demote_idle": true
        },
        "4": {
          // Diamond: no promotion (already highest tier), heavier demotion
          "promotion": 0,
          "demotion": 0.4,
          "demote_idle": true
        }
      }
    }
  }
}

Variation: cooperative completion

If you want every player to have a chance to finish and earn rewards, set score_target_players equal to cohort_size. For example, with cohort_size: 7 and score_target_players: 7, all 7 players can reach the target and earn position-based rewards. The cohort only completes when all players finish (or the phase timer expires). This shifts the feel from competitive elimination to a cooperative race where everyone can succeed, but faster players still earn better rewards.

Example: Multi-stage tournament #

Players progress through escalating difficulty stages, implemented as tiers. Each stage has a harder target, a smaller cohort, and better rewards. Only the first player to finish each stage advances, and everyone else stays and can try again immediately. This is another popular implementation of event leaderboards, found in titles such as Royal Match’s Space Missions.

How it works: A weekend event features 3 tiers. All players start at tier 3. Within each stage, players race to complete a streak of consecutive levels. The first player to hit the target wins, advances to the next tier and faces tougher competition. Players who don’t win stay at their current tier and re-roll into a new cohort. At the end of the event, everyone resets back to tier 3.

Example configuration

  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
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110

{
  "event_leaderboards": {
    "tower_climb": {
      "name": "Tower Climb",
      "description": "Climb the tower! Each stage gets harder.",
      "category": "competitive",
      "ascending": false,
      "operator": "set", // Client sends current streak count; sends 0 on failure to reset
      "reset_schedule": "0 12 * * 5", // New phase every Friday at noon UTC
      "cohort_size": 5, // Default cohort size (overridden per tier below)
      "max_num_score": 0, // No limit on score submissions
      "tiers": 3, // 3 stages of escalating difficulty
      "max_idle_tier_drop": 0,
      "start_time_sec": 0,
      "end_time_sec": 0,
      "duration": 259200, // 3 days (Friday–Monday)
      "max_rolls": 9999, // Effectively unlimited attempts per phase
      "tier_delta_per_phase": -3, // Reset everyone to stage 1 (tier 0) when the phase ends
      "tier_overrides": {
        "0": {
          // Stage 1: targets escalate and cohorts shrink per stage
          "name": "Moon",
          "description": "Clear 3 consecutive encounters to advance!",
          "cohort_size": 5,
          "score_target": 3,
          "score_target_players": 1 // Only the first player to finish wins and advances
        },
        "1": {
          "name": "Mars",
          "description": "Clear 5 consecutive encounters to advance!",
          "cohort_size": 4,
          "score_target": 5,
          "score_target_players": 1
        },
        "2": {
          "name": "Saturn",
          "description": "Clear 7 consecutive encounters to prove your mastery!",
          "cohort_size": 3,
          "score_target": 7,
          "score_target_players": 1
        }
      },
      "reward_tiers": {
        "0": [
          {
            "name": "Winner",
            "rank_min": 1,
            "rank_max": 1,
            "tier_change": 1, // Winner is promoted to the next stage
            "reward": {
              "guaranteed": {
                "currencies": {
                  "coins": { "min": 1000, "max": 1000 }
                }
              }
            }
          },
          {
            "name": "Participant",
            "rank_min": 2,
            "rank_max": 5,
            "tier_change": 0 // Non-winners stay and can try again
          }
        ],
        "1": [
          {
            "name": "Winner",
            "rank_min": 1,
            "rank_max": 1,
            "tier_change": 1,
            "reward": {
              "guaranteed": {
                "currencies": {
                  "coins": { "min": 2500, "max": 2500 }
                }
              }
            }
          },
          {
            "name": "Participant",
            "rank_min": 2,
            "rank_max": 4,
            "tier_change": 0
          }
        ],
        "2": [
          {
            "name": "Champion",
            "rank_min": 1,
            "rank_max": 1,
            "tier_change": 0, // Top stage: nowhere higher to go
            "reward": {
              "guaranteed": {
                "currencies": {
                  "coins": { "min": 5000, "max": 5000 }
                }
              }
            }
          },
          {
            "name": "Participant",
            "rank_min": 2,
            "rank_max": 3,
            "tier_change": 0
          }
        ]
      }
    }
  }
}

Player progression #

Event Leaderboards implement a tier system that promotes progression over time:

• Players are assigned to tiers (e.g. Bronze, Silver, Gold) with tier 0 being the lowest
• The system supports configurable numbers of tiers
• Each tier can have different reward structures, cohort sizes, score targets, and competitive dynamics via tier_overrides

Promotion and demotion #

Change zones (primary method): The system uses configurable promotion and demotion percentages to determine tier movement. A promotion percentage defines what portion of top performers advance to higher tiers, while a demotion percentage determines how many bottom performers drop down. These percentages can be configured per tier to create different competitive dynamics at various skill levels.

Reward tiers (fallback method): When change zones aren’t configured, the system uses reward tiers for advancement. Each reward tier defines specific rank ranges and their associated tier changes, allowing players within certain positions to move up, down, or remain in their current tier.

Handling idle players #

The system includes configurable rules for handling inactive players. When idle demotion is enabled (demote_idle in change zones), players who fail to submit scores are automatically demoted. The system calculates tier drops based on how many complete phases they’ve missed, with a configurable maximum limit (max_idle_tier_drop) that caps the number of tiers they can drop when they return. Idle demotion only applies when a phase has fully expired; re-rolling within an active phase does not trigger idle penalties.

Additionally, tier_delta_per_phase can be used to apply an automatic tier adjustment when a phase expires, on top of regular change zone rules. For example, setting it to -1 creates a decay mechanic where players must actively participate to maintain their tier.

Calculating tiers #

Tier changes are calculated when players roll into a new phase, considering:

• Previous rank within the cohort
• Whether the player was idle (no score submissions)
• Applicable change zones or reward tier rules
• Maximum tier drop limits for idle players
• Any tier_delta_per_phase adjustments

Players cannot drop below tier 0 or exceed the maximum configured tier, ensuring the system maintains appropriate boundaries for all participants.

Configuration #

This section describes every configurable property of Event Leaderboards. The JSON schema defines an event_leaderboards object containing an individual object for each event leaderboard you wish to define. You can configure as many Event Leaderboards as needed for your game. Depending on your use case, some fields will not be needed at all. See Quick reference.

EventLeaderboard config #

Properties that describe the behaviour of the overall Event Leaderboard. For complete examples of various JSON configurations, see Time-based events and Score-based events.

Example tier_overrides

Use tier_overrides to give each tier its own settings. Any field not specified in the override inherits from the top-level config:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

"tier_overrides": {
  "0": {
    "name": "Bronze League",
    "description": "The starting league.",
    "cohort_size": 50,
    "score_target": 10
  },
  "1": {
    "name": "Silver League",
    "description": "Tougher competition, better rewards.",
    "cohort_size": 30,
    "score_target": 20
  }
}

RewardTier config #

Properties that describe the rewards players receive for achieving certain rankings within their tier, including any upward or downward progression. See Promotion and demotion.

ChangeZone config #

Properties that determine the percentile of players who should move up or down a tier. See Promotion and demotion.

Score operators #

The score operator determines how new score submissions are processed. Can be overridden on the client.

Quick reference #

Not every field is relevant to every event type. The table below shows the primary fields for each type of competition. See the full property tables above for all available fields.

Event Leaderboards vs Challenges #

While both Event Leaderboards and Challenges provide competitive gameplay features, they serve different purposes and have distinct characteristics. Event Leaderboards are designed for structured, recurring competitive events with predefined cohorts and tiered progression. Challenges, on the other hand, are intended for on-demand and player-driven competitive experiences.

The following table outlines their differences:

The key distinction is that Event Leaderboards are designed for creating fair, engaging competitive experiences that scale well with large player bases, while maintaining player engagement through tiered progression systems.

Additional resources #

• Hiro Event Leaderboards sample project
• Mage Mayhem sample project
• How to implement weekly event leaderboards in a match 3 game
• Nakama Leaderboards
• Server-side implementation of event leaderboards
• Event leaderboards in Unity
• Event leaderboards in Unreal