# Event Leaderboards

**URL:** https://heroiclabs.com/docs/hiro/unreal/event-leaderboards/
**Keywords:** event leaderboards, hiro
**Categories:** hiro, unreal, event-leaderboards

---


# Event Leaderboards

Read more about the Event Leaderboards system in Hiro [here](../../concepts/event-leaderboards/).

## Event leaderboard response

The event leaderboard response object includes the following properties:

| Property                | Type    | Description                                                           |
| ----------------------- | ------- | --------------------------------------------------------------------- |
| `BestRank`              | `int64` | 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.         |
| `IsActive`              | `bool`  | Whether the event leaderboard's current phase is live.                |
| `MaxRolls`              | `int64` | Maximum rolls allowed per phase.                                      |
| `RerollCountFreeze`     | `bool`  | Whether the next roll is "free" (does not count against `MaxRolls`).  |
| `RollCooldownSec`       | `int64` | Effective cooldown between rolls, in seconds.                         |
| `Rolls`                 | `int64` | Number of rolls the player has used this phase.                       |
| `ScoreTarget`           | `int64` | Target score for cohort completion.                                   |
| `ScoreTargetPlayers`    | `int64` | How many players must reach the target.                               |
| `Tier`                  | `int32` | The player's current tier (0-indexed).                                |
| `TierDeltaPerPhase`     | `int64` | Tier adjustment applied when a phase expires.                         |
| `ClaimTimeSec`          | `int64` | Unix timestamp when the player claimed their reward (0 if unclaimed). |
| `EndTimeSec`            | `int64` | Unix timestamp when the player's current cohort is scheduled to end.  |
| `ExpiryTimeSec`         | `int64` | Unix timestamp when the player's phase pointer expires.               |
| `RollCooldownEndsSec`   | `int64` | When the current cooldown expires (UNIX timestamp).                   |
| `ScoreTimeLimitEndsSec` | `int64` | When this player's time limit expires (UNIX timestamp).               |
| `ScoreTimeLimitSec`     | `int64` | Per-player time limit from roll time, in seconds.                     |
| `StartTimeSec`          | `int64` | Unix 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.

{{< table name="gdk.concepts.event-leaderboards.event-leaderboard-state">}}

## List event leaderboards

You can list all the available event leaderboards to the player by not specifying any categories in the request.

```cpp
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.

```cpp
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.

```cpp
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.

```cpp
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.

```cpp
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.

```cpp
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.

```cpp
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.

{{< note "warning" >}}
This is intended for debugging use only.
{{< / note >}}

```cpp
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());
}

// Removes user from their current cohort, allowing re-enrollment
FHiroEventLeaderboardDebugUnenrollRequest UnenrollRequest;
UnenrollRequest.Id = TEXT("leaderboard_1");

FHiroOnEventLeaderboardDebugUnenroll OnEventLeaderboardDebugUnenroll;
OnEventLeaderboardDebugUnenroll.AddDynamic(this, &AMyActor::OnEventLeaderboardDebugUnenroll);
FOnError OnUnenrollError;

HiroClient->EventLeaderboardDebugUnenroll(Session, UnenrollRequest, OnEventLeaderboardDebugUnenroll, OnUnenrollError);

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

```