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
| # 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)
|
Next Steps
#