# Event Leaderboards **URL:** https://heroiclabs.com/docs/hiro/concepts/event-leaderboards/ **Keywords:** event leaderboards, hiro **Categories:** hiro, event-leaderboards, concepts ---
}}" style="width: 100%;" >
Star Tournament in Wordscapes by PeopleFun
# 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](#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](#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. {{< note "outline" "" hide_icon>}} Ready to try it yourself? Explore the [Event Leaderboard sample project](../../../sample-projects/unity/hiro-event-leaderboards/). {{}} ## 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 tournaments](#example-multi-stage-tournaments) for an example. When a new phase begins, all roll counts reset and players start fresh.
}}" style="width: 100%;" >
An active Event Leaderboard containing multiple phases
### 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](#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. | `max_rolls` value | Behavior | | ----------------- | --------------------------------------------------------------------------------------- | | `0` or `1` | Player joins one cohort per phase. This is the default behavior. `0` is treated as `1`. | | `N` | Player gets 1 initial roll + (N-1) re-rolls within the phase. | 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. {{< note "important">}} The roll count only increments when reroll count freeze is not active. Certain outcomes (like promotions) can be configured to grant free rolls that don't count against the limit. See [Reroll count freeze](#reroll-count-freeze) for details. {{< /note >}} ### 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](../../server-framework/event-leaderboards/#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](../../unity/event-leaderboards/) for usage examples. {{< note "important">}} Claiming is required before re-rolling. If a player doesn't claim, they cannot roll into a new cohort. They remain on their current cohort until the phase expires. At phase expiry, the player can roll into a new phase without needing to claim the old one. {{< /note >}} ### 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](#tiers) below). For more details on reward contents, see [Rewards](../economy/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. {{< note "important">}} _Reward tiers_ and _tiers_ are different concepts. Reward tiers are rank brackets within a single cohort that determine what prizes a player receives (e.g. "Top 3", "Ranks 4–10"). Tiers are persistent progression levels that carry over across phases. The semantic naming of reward tiers and progression tiers is up to you. {{< /note >}} ### 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** {{< code hideable="false" filename="event-leaderboards.json">}} ```json { "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 } } } } } ] } } } } ``` {{< /code >}} ## 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](https://dreamgames.helpshift.com/hc/en/3-royal-match/faq/113-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** {{< code hideable="false" filename="event-leaderboards.json">}} ```json { "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 } } } } } ``` {{< /code >}} **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 tournaments 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](https://dreamgames.helpshift.com/hc/en/3-royal-match/faq/118-space-mission-1652306365/). **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.
}}" style="width: 100%;" >
Players re-roll multiple times into new cohorts within a single phase
**Example configuration** {{< code hideable="false" filename="event-leaderboards.json">}} ```json { "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 } ] } } } } ``` {{< /code >}} ## 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](#quick-reference). {{< table name="gdk.concepts.event-leaderboards.event-leaderboards-system">}} ### EventLeaderboard config Properties that describe the behaviour of the overall Event Leaderboard. For complete examples of various JSON configurations, see [Time-based events](#time-based-events) and [Score-based events](#score-based-events). {{< table name="gdk.concepts.event-leaderboards.event-leaderboard">}} **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: {{< code hideable="false" filename="event-leaderboards.json">}} ```json "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 } } ``` {{< /code >}} ### 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](#promotion-and-demotion). {{< table name="gdk.concepts.event-leaderboards.reward-tier">}} ### ChangeZone config Properties that determine the percentile of players who should move up or down a tier. See [Promotion and demotion](#promotion-and-demotion). {{< table name="gdk.concepts.event-leaderboards.change-zone">}} ### Score operators The score operator determines how new score submissions are processed. Can be overridden on the client. {{< table name="gdk.concepts.event-leaderboards.score-operators">}} ### 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. | Field | Time-based | Score-based | | --------------------------------------------------- | ------------ | ------------ | | `name` | Required | Required | | `description` | Required | Required | | `operator` | Required | Required | | `ascending` | Required | Required | | `cohort_size` | Required | Required | | `tiers` | Required | Required | | `duration` | Required | Required | | `reset_schedule` or `start_time_sec`/`end_time_sec` | Required | Required | | `reward_tiers` or `change_zones` | At least one | At least one | | `max_idle_tier_drop` | Optional | Optional | | `score_target` | — | Required | | `max_rolls` | — | Required | | `score_target_players` | — | Optional | | `score_time_limit_sec` | — | Optional | | `roll_cooldown_sec` | — | Optional | ## 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: {{< table name="gdk.concepts.event-leaderboards.event-leaderboard-comparison" >}} 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](../../../sample-projects/unity/hiro-event-leaderboards) - [Mage Mayhem sample project](../../../sample-projects/games/mage-mayhem) - [How to implement weekly event leaderboards in a match 3 game](../../guides/gameplay-mechanics/event-leaderboard/) - [Nakama Leaderboards](../../../nakama/concepts/leaderboards/) - [Server-side implementation of event leaderboards](../../server-framework/event-leaderboards/) - [Event leaderboards in Unity](../../unity/event-leaderboards/) - [Event leaderboards in Unreal](../../unreal/event-leaderboards/)