Event Leaderboards

Read more about the Event Leaderboards system in Hiro here.

Event leaderboard response #

The event leaderboard response object includes the following properties:

PropertyTypeDescription
BestRankint64Best rank achieved across cohorts this phase.
CanClaimboolWhether the player can claim their reward.
CanRollboolWhether the player can roll into a new cohort right now.
CanRollWithClaimboolWhether the player can claim and roll in a single call.
CanUpdateboolWhether the player can submit scores to their current cohort.
IsActiveboolWhether the event leaderboard’s current phase is live.
MaxRollsint64Maximum rolls allowed per phase.
RerollCountFreezeboolWhether the next roll is “free” (does not count against MaxRolls).
RollCooldownSecint64Effective cooldown between rolls, in seconds.
Rollsint64Number of rolls the player has used this phase.
ScoreTargetint64Target score for cohort completion.
ScoreTargetPlayersint64How many players must reach the target.
Tierint32The player’s current tier (0-indexed).
TierDeltaPerPhaseint64Tier adjustment applied when a phase expires.
ClaimTimeSecint64Unix timestamp when the player claimed their reward (0 if unclaimed).
EndTimeSecint64Unix timestamp when the player’s current cohort is scheduled to end.
ExpiryTimeSecint64Unix timestamp when the player’s phase pointer expires.
RollCooldownEndsSecint64When the current cooldown expires (UNIX timestamp).
ScoreTimeLimitEndsSecint64When this player’s time limit expires (UNIX timestamp).
ScoreTimeLimitSecint64Per-player time limit from roll time, in seconds.
StartTimeSecint64Unix timestamp when the player’s current cohort started.

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.

IsActiveCanClaimCanRollDescription
FALSEFALSEFALSEVisible, but inactive. No actions are possible.
FALSETRUEFALSEVisible, but inactive. A reward from a previous phase can be claimed.
TRUEFALSEFALSEActive, a valid cohort exists and the player can submit scores (CanUpdate is true).
TRUEFALSETRUEActive, need to roll to get a cohort.
TRUETRUEFALSEActive, 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 not specifying any categories in the request.

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

FHiroEventLeaderboardList Request;

FHiroOnEventLeaderboardList OnEventLeaderboardList;
OnEventLeaderboardList.AddDynamic(this, &AMyActor::OnEventLeaderboardList);
FOnError OnError;

HiroClient->EventLeaderboardList(Session, Request, OnEventLeaderboardList, OnError);

void AMyActor::OnEventLeaderboardList(const FHiroEventLeaderboards& EventLeaderboards)
{
    UE_LOG(LogTemp, Log, TEXT("%s"), *EventLeaderboards.ToJson());
}

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

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

FHiroEventLeaderboardList Request;
Request.Categories.Append(TEXT("level_completed"));
Request.Categories.Append(TEXT("race"));

FHiroOnEventLeaderboardList OnEventLeaderboardList;
OnEventLeaderboardList.AddDynamic(this, &AMyActor::OnEventLeaderboardList);
FOnError OnError;

HiroClient->EventLeaderboardList(Session, Request, OnEventLeaderboardList, OnError);

void AMyActor::OnEventLeaderboardList(const FHiroEventLeaderboards& EventLeaderboards)
{
    UE_LOG(LogTemp, Log, TEXT("%s"), *EventLeaderboard.ToJson());
}

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

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

FHiroEventLeaderboardList Request;
Request.WithScores = true;

FHiroOnEventLeaderboardList OnEventLeaderboardList;
OnEventLeaderboardList.AddDynamic(this, &AMyActor::OnEventLeaderboardList);
FOnError OnError;

HiroClient->EventLeaderboardList(Session, Request, OnEventLeaderboardList, OnError);

void AMyActor::OnEventLeaderboardList(const FHiroEventLeaderboards& EventLeaderboards)
{
    UE_LOG(LogTemp, Log, TEXT("%s"), *EventLeaderboard.ToJson());
}

Get an event leaderboard #

Get a specified event leaderboard defined for the game.

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

FHiroEventLeaderboardGet Request;
Request.Id = TEXT("leaderboard_1");

FHiroOnEventLeaderboardGet OnEventLeaderboardGet;
OnEventLeaderboardGet.AddDynamic(this, &AMyActor::OnEventLeaderboardGet);
FOnError OnError;

HiroClient->EventLeaderboardGet(Session, Request, OnEventLeaderboardGet, OnError);

void AMyActor::OnEventLeaderboardGet(const FHiroEventLeaderboard& EventLeaderboard)
{
    UE_LOG(LogTemp, Log, TEXT("%s"), *EventLeaderboard.ToJson());
}

Update event leaderboard record #

Update an event leaderboard record for a user.

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

FHiroEventLeaderboardUpdate Request;
Request.Id = TEXT("leaderboard_1");
Request.Score = 100;
Request.Subscore = 10;

FHiroOnEventLeaderboardUpdate OnEventLeaderboardUpdate;
OnEventLeaderboardUpdate.AddDynamic(this, &AMyActor::OnEventLeaderboardUpdate);
FOnError OnError;

HiroClient->EventLeaderboardUpdate(Session, Request, OnEventLeaderboardUpdate, OnError);

void AMyActor::OnEventLeaderboardUpdate(const FHiroEventLeaderboard& EventLeaderboard)
{
    UE_LOG(LogTemp, Log, TEXT("%s"), *EventLeaderboard.ToJson());
}

Claim event leaderboard reward #

Claim an event leaderboard reward for a user.

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

FHiroEventLeaderboardClaim Request;
Request.Id = TEXT("leaderboard_1");

FHiroOnEventLeaderboardClaim OnEventLeaderboardClaim;
OnEventLeaderboardClaim.AddDynamic(this, &AMyActor::OnEventLeaderboardClaim);
FOnError OnError;

HiroClient->EventLeaderboardClaim(Session, Request, OnEventLeaderboardClaim, OnError);

void AMyActor::OnEventLeaderboardClaim(const FHiroEventLeaderboard& EventLeaderboard)
{
    UE_LOG(LogTemp, Log, TEXT("%s"), *EventLeaderboard.ToJson());
}

Roll a new cohort #

Roll a new cohort for the specified event leaderboard.

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

FHiroEventLeaderboardRoll Request;
Request.Id = TEXT("leaderboard_1");

FHiroOnEventLeaderboardRoll OnEventLeaderboardRoll;
OnEventLeaderboardRoll.AddDynamic(this, &AMyActor::OnEventLeaderboardRoll);
FOnError OnError;

HiroClient->EventLeaderboardRoll(Session, Request, OnEventLeaderboardRoll, OnError);

void AMyActor::OnEventLeaderboardRoll(const FHiroEventLeaderboard& EventLeaderboard)
{
    UE_LOG(LogTemp, Log, TEXT("%s"), *EventLeaderboard.ToJson());
}

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
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

FHiroEventLeaderboardDebugFillRequest FillRequest;
FillRequest.Id = TEXT("leaderboard_1");
FillRequest.TargetCount = 50; // Optional target cohort size to fill to, otherwise fill to the max cohort size.

FHiroEventLeaderboardDebugRandomScoresRequest ScoresRequest;
ScoresRequest.Id = TEXT("leaderboard_1");
ScoresRequest.Min = 1;
ScoresRequest.Max = 100;
ScoresRequest.SubscoreMin = 1;
ScoresRequest.SubscoreMax = 100;

FHiroOnEventLeaderboardDebugFill OnEventLeaderboardDebugFill;
OnEventLeaderboardDebugFill.AddDynamic(this, &AMyActor::OnEventLeaderboardDebugFill);
FOnError OnFillError;

FHiroOnEventLeaderboardDebugRandomScores OnEventLeaderboardDebugRandomScores;
OnEventLeaderboardDebugRandomScores.AddDynamic(this, &AMyActor::OnEventLeaderboardDebugRandomScores);
FOnError OnScoresError;

// Fills cohort with debug players
HiroClient->EventLeaderboardDebugFill(Session, FillRequest, OnEventLeaderboardDebugFill, OnFillError);

// Sets randomly generated scores between a range for other players (does not change the user's score)
HiroClient->EventLeaderboardDebugRandomScores(Session, ScoresRequest, OnEventLeaderboardDebugRandomScores, OnScoresError);

void AMyActor::OnEventLeaderboardDebugFill(const FHiroEventLeaderboard& EventLeaderboard)
{
    UE_LOG(LogTemp, Log, TEXT("%s"), *EventLeaderboard.ToJson());
}

void AMyActor::OnEventLeaderboardDebugRandomScores(const FHiroEventLeaderboard& EventLeaderboard)
{
    UE_LOG(LogTemp, Log, TEXT("%s"), *EventLeaderboard.ToJson());
}