Event Leaderboards

Read more about the Event Leaderboards system in Hiro here.

Initialize the event leaderboards system #

The event leaderboards system system relies on the Nakama System and an ILogger, both must be passed in as dependencies via the constructor.

1
2
var eventLeaderboardsSystem = new EventLeaderboardsSystem(logger, nakamaSystem);
systems.Add(eventLeaderboardsSystem);

Event leaderboard response #

The IEventLeaderboard response object includes the following properties:

Property	Type	Description
`BestRank`	`long`	Best rank achieved across cohorts this phase.
`CanClaim`	`bool`	Whether the player can claim their reward.
`CanRoll`	`bool`	Whether the player can roll into a new cohort right now.
`CanRollWithClaim`	`bool`	Whether the player can claim and roll in a single call.
`CanUpdate`	`bool`	Whether the player can submit scores to their current cohort.
`Count`	`long`	Number of players currently in the cohort.
`IsActive`	`bool`	Whether the event leaderboard’s current phase is live.
`MaxCount`	`long`	Maximum number of players the cohort can hold.
`MaxRolls`	`long`	Maximum rolls allowed per phase.
`RerollCountFreeze`	`bool`	Whether the next roll is “free” (does not count against `MaxRolls`).
`RollCooldownSec`	`long`	Effective cooldown between rolls, in seconds.
`Rolls`	`long`	Number of rolls the player has used this phase.
`ScoreTarget`	`long`	Target score for cohort completion.
`ScoreTargetPlayers`	`long`	How many players must reach the target.
`Tier`	`int`	The player’s current tier (0-indexed).
`TierDeltaPerPhase`	`long`	Tier adjustment applied when a phase expires.
`ClaimTimeSec`	`long`	Unix timestamp when the player claimed their reward (0 if unclaimed).
`EndTimeSec`	`long`	Unix timestamp when the player’s current cohort is scheduled to end.
`ExpiryTimeSec`	`long`	Unix timestamp when the player’s phase pointer expires.
`RollCooldownEndsSec`	`long`	When the current cooldown expires (UNIX timestamp).
`ScoreTimeLimitEndsSec`	`long`	When this player’s time limit expires (UNIX timestamp).
`ScoreTimeLimitSec`	`long`	Per-player time limit from roll time, in seconds.
`StartTimeSec`	`long`	Unix timestamp when the player’s current cohort started.

Score entry properties #

IEventLeaderboard.Scores is a collection of IEventLeaderboardScore objects, one per player in the cohort.

Property	Type	Description
`Id`	`string`	User ID of the player.
`Username`	`string`	Username of the player.
`DisplayName`	`string`	Display name of the player.
`AvatarUrl`	`string`	Avatar URL of the player.
`Rank`	`long`	The player’s rank within the cohort. `0` means the player hasn’t submitted a score yet.
`Score`	`long`	The player’s primary score.
`Subscore`	`long`	The player’s secondary score.
`NumScores`	`long`	Number of score submissions by this player.
`TierDelta`	`int`	Predicted tier change if the current phase ended now. Positive: promotion (value = tiers gained) Negative: demotion (value = tiers lost) `0`: no change
`Metadata`	`string`	Custom metadata attached to this score entry.
`CreateTimeSec`	`long`	Unix timestamp when the player joined this cohort.
`UpdateTimeSec`	`long`	Unix timestamp of the player’s last score submission.

Use TierDelta to show players whether they’re on track for promotion, demotion, or no change, while the event is still live.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
foreach (var score in eventLeaderboard.Scores)
{
    var tierStatus = score.TierDelta switch
    {
        > 0 => $"▲ Promotion (+{score.TierDelta})",
        < 0 => $"▼ Demotion ({score.TierDelta})",
        _   => "— No change"
    };

    Debug.Log($"#{score.Rank} {score.Username}: {score.Score} — {tierStatus}");
}

Determine event leaderboard state #

When the server returns an Event Leaderboard, its current state is represented by a combination of boolean properties. Check if the player can claim rewards and roll into a new cohort simultaneously by reading the CanRollWithClaim property in the response.


IsActive	CanClaim	CanRoll	Description
`FALSE`	`FALSE`	`FALSE`	Visible, but inactive. No actions are possible.
`FALSE`	`TRUE`	`FALSE`	Visible, but inactive. A reward from a previous phase can be claimed.
`TRUE`	`FALSE`	`FALSE`	Active, a valid cohort exists and the player can submit scores (`CanUpdate` is `true`).
`TRUE`	`FALSE`	`TRUE`	Active, need to roll to get a cohort.
`TRUE`	`TRUE`	`FALSE`	Active, a completed cohort exists with an unclaimed reward. The player has no remaining rolls after claiming, or is waiting for a roll cooldown to expire.

List event leaderboards #

You can list all the available event leaderboards to the player by passing null as an argument.

1
var eventLeaderboards = await eventSystem.ListEventLeaderboardsAsync(null);

You can filter down the event leaderboards to only include those that belong to at least one of the given categories.

1
2
IEnumerable<string> categories = new List<string> { "level_completion", "race"};
var eventLeaderboards = await eventSystem.ListEventLeaderboardsAsync(categories);

By default, the response doesn’t include the scores of the event leaderboards. To have the response returning with the scores, set the boolean with_score on the request to true.

1
var eventLeaderboards = await eventSystem.ListEventLeaderboardsAsync(null, true);

Get an individual event leaderboard #

You can get an individual event leaderboard, including it’s records and information on it’s rewards.

1
var eventLeaderboard = await eventLeaderboardsSystem.GetEventLeaderboardAsync("<leaderboardId>");

Submit an event leaderboard score #

You can submit an event leaderboard score for the user. Check CanUpdate on the response to determine whether the player can still submit scores to their current cohort.

1
2
3
4
5
6
7
8
9
var score = 100;
var subscore = 10;
var eventLeaderboard = await eventLeaderboardsSystem.UpdateEventLeaderboardAsync("<leaderboardId>", score, subscore);

// Check if further score submissions are allowed
if (!eventLeaderboard.CanUpdate)
{
    // The player can no longer submit scores to this cohort
}

Claim rewards #

You can claim event leaderboard rewards for the user.

1
2
3
4
if (eventLeaderboard.CanClaim)
{
    eventLeaderboard = await eventLeaderboardsSystem.ClaimEventLeaderboardAsync("<leaderboardId>");
}

Check CanClaim to determine whether the player has a reward available. The server sets CanClaim to false within the claim request, so the IEventLeaderboard returned by ClaimEventLeaderboardAsync already reflects the claimed state. Await the call and use the returned object for any follow-up logic.

Claim state isn't cached offline

ClaimEventLeaderboardAsync doesn’t update the local event leaderboard state used by offline support. When the client is offline or the request fails with a transient error, UpdateEventLeaderboardAsync returns that cached state, which can still show CanClaim as true after a claim.

Roll into a cohort #

You can roll (or re-roll) the user into a cohort for a specific event leaderboard. The first roll in a phase places the player into a cohort for the first time. Subsequent rolls within the same phase are re-rolls, where the player leaves a completed cohort and joins a new one with fresh opponents.

1
2
// Roll into a cohort (first roll or re-roll after claiming separately)
var eventLeaderboard = await eventLeaderboardsSystem.RollEventLeaderboardAsync("<leaderboardId>");

After rolling, eventLeaderboard.Count and eventLeaderboard.MaxCount show how many players are currently in the cohort and the maximum it can hold.

1
Debug.Log($"Cohort: {eventLeaderboard.Count}/{eventLeaderboard.MaxCount} players");

To claim the current reward and roll into a new cohort in a single call, pass claimReward: true. This is the recommended approach for re-rolling as it avoids an extra round-trip.

1
2
// Claim reward and roll into a new cohort in one call
var eventLeaderboard = await eventLeaderboardsSystem.RollEventLeaderboardAsync("<leaderboardId>", claimReward: true);

Multi-roll game loop #

For score-based events where players can compete in multiple cohorts within a single phase, the typical flow looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
// 1. Roll into the first cohort
var el = await eventLeaderboardsSystem.RollEventLeaderboardAsync("score_rush");

// 2. Submit scores while the cohort is active
while (el.CanUpdate)
{
    el = await eventLeaderboardsSystem.UpdateEventLeaderboardAsync("score_rush", playerScore);
}

// 3. Check if can the player can roll into a cohort and claim rewards
if (el.CanRollWithClaim || el.CanRoll)
{
   // Claim and roll in one call
    el = await eventLeaderboardsSystem.RollEventLeaderboardAsync("score_rush", claimReward: el.CanRollWithClaim);
}
else if (el.CanClaim)
{
    // Just claim, done for this phase (or waiting for cooldown)
    el = await eventLeaderboardsSystem.ClaimEventLeaderboardAsync("score_rush");
}

Debug an event leaderboard #

You can fill an event leaderboard with dummy users and assign random scores to them for testing purposes.

This is intended for debugging use only.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
var leaderboardId = "<leaderboardId>";
var targetCount = 50; // Optional target cohort size to fill to, otherwise fill to the max cohort size.

var minScore = 1;
var maxScore = 100;
var @operator = ApiOperator.SET;
var subscoreMin = 1;
var subscoreMax = 100;

// Fills cohort with debug players
await eventLeaderboardsSystem.DebugFillAsync(leaderboardId, targetCount);

// Sets randomly generated scores between a range for other players (does not change the user's score)
await eventLeaderboardsSystem.DebugRandomScoresAsync(leaderboardId, minScore, maxScore, @operator, subscoreMin, subscoreMax);

// Removes the user from their current cohort, allowing re-enrollment
await eventLeaderboardsSystem.DebugUnenrollAsync(leaderboardId);

Additional information #

Hiro Event Leaderboards sample project

Heroic Cloud