View as Markdown

Event Leaderboards

The Event Leaderboards system enables competitive gameplay through event-specific leaderboards. Learn more in the Event Leaderboards concept guide.

Overview #

Event Leaderboards allow your game to:

  • List available event leaderboards.
  • Update player scores and standings.
  • Claim rewards based on leaderboard performance.
  • Manage leaderboard cohorts.

Before You Start #

Ensure you have:

  • Unity project configured with Hiro SDK.
  • Nakama system integrated (guide).

Working with Event Leaderboards #

Listing Event Leaderboards #

Retrieve all available leaderboards:

1
2
3

request = EventLeaderboardList()
event_leaderboards = await hiro_client.event_leaderboard_list(request)
print(event_leaderboards)

Filtering by Categories #

Retrieve leaderboards filtered by category:

1
2
3
4
5

request = EventLeaderboardList()
request.categories = ["level_complete", "race"]

event_leaderboards = await hiro_client.event_leaderboard_list(request)
print(event_leaderboards)

Including Scores #

Retrieve leaderboards with scores included:

1
2
3
4
5

request = EventLeaderboardList()
request.with_scores = True

event_leaderboards = await hiro_client.event_leaderboard_list(request)
print(event_leaderboards)

Getting a Specific Event Leaderboard #

Retrieve details for a specific leaderboard:

1
2
3
4
5

request = EventLeaderboardGet()
request.id = "leaderboard_1"

event_leaderboard = await hiro_client.event_leaderboard_get(request)
print(event_leaderboard)

Updating Leaderboard Records #

Update a player’s leaderboard score:

1
2
3
4
5
6
7

request = EventLeaderboardUpdate()
request.id = "leaderboard_1"
request.score = 100
request.subscore = 10

event_leaderboard = await hiro_client.event_leaderboard_update(request)
print(event_leaderboard)

Claiming Leaderboard Rewards #

Claim rewards earned from leaderboard events:

1
2
3
4
5

request = EventLeaderboardClaim()
request.id = "leaderboard_1"

event_leaderboard = await hiro_client.event_leaderboard_claim(request)
print(event_leaderboard)

Rolling a New Cohort #

Start a new cohort for an event leaderboard:

1
2
3
4
5

request = EventLeaderboardRoll()
request.id = "leaderboard_1"

event_leaderboard = await hiro_client.event_leaderboard_roll(request)
print(event_leaderboard)

Debugging Event Leaderboards #

Warning: Intended for debugging use only.

Fill event leaderboards with dummy data and assign random scores:

 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

# Filling leaderboard with debug users
fill_request = EventLeaderboardDebugFillRequest()
fill_request.id = "leaderboard_1"
fill_request.target_count = 50  # Optional target cohort size

fill_leaderboard = await hiro_client.event_leaderboard_debug_fill(fill_request)
print(fill_leaderboard)

# Assigning random scores
scores_request = EventLeaderboardDebugRandomScoresRequest()
scores_request.id = "leaderboard_1"
scores_request.min = "1"
scores_request.max = "100"
scores_request.subscore_min = "1"
scores_request.subscore_max = "100"

scores_leaderboard = await hiro_client.event_leaderboard_debug_random_scores(scores_request)
print(scores_leaderboard)

# Removes user from their current cohort, allowing re-enrollment
unenroll_request = EventLeaderboardDebugUnenrollRequest()
unenroll_request.id = "leaderboard_1"

unenroll_leaderboard = await hiro_client.event_leaderboard_debug_unenroll(unenroll_request)
print(unenroll_leaderboard)

Next Steps #