Leaderboards

The Leaderboards system manages competitive player rankings based on scores. Learn more in the Leaderboards concept guide .

The methods below require Hiro 1.33 or later. If you are on an earlier version, see Hiro 1.32 and earlier .

Overview #

The Leaderboards system enables your game to:

Retrieve defined leaderboards.
Track and display player rankings.

Before you start #

Make sure you have:

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

Working with leaderboards #

Get all leaderboards #

List all available leaderboards.

1
2
3
4
request = LeaderboardListRequest()

leaderboard_list = await hiro_client.leaderboard_list(session, request)
print(leaderboard_list)

Filter by category:

1
2
3
4
5
request = LeaderboardListRequest()
request.categories = ["Tournament"]

leaderboard_list = await hiro_client.leaderboard_list(session, request)
print(leaderboard_list)

Get a leaderboard #

Get a specified leaderboard by ID.

1
2
3
4
5
request = LeaderboardGet()
request.id = "GalacticChampions"

leaderboard = await hiro_client.leaderboard_get(session, request)
print(leaderboard)

Submit a score #

Submit a score to a leaderboard.

1
2
3
4
5
6
7
request = LeaderboardUpdate()
request.id = "GalacticChampions"
request.set_score_numeric(1500)
request.set_subscore_numeric(0)

leaderboard_score = await hiro_client.leaderboard_update(session, request)
print(leaderboard_score)

List scores #

List scores on a leaderboard. Pass owner_ids to retrieve scores for specific owners.

1
2
3
4
5
6
7
request = LeaderboardScoresListRequest()
request.id = "GalacticChampions"
request.owner_ids = ["userId1", "userId2"]
request.limit = 100

score_list = await hiro_client.leaderboard_scores_list(session, request)
print(score_list)

Filter by region:

1
2
3
4
5
6
7
request = LeaderboardScoresListRequest()
request.id = "GalacticChampions"
request.region = "EU"
request.limit = 100

score_list = await hiro_client.leaderboard_scores_list(session, request)
print(score_list)

List scores around owner #

List scores centred around a specific owner.

1
2
3
4
5
6
7
request = LeaderboardScoresListAroundOwnerRequest()
request.id = "GalacticChampions"
request.owner_id = session.user_id
request.limit = 10

score_list = await hiro_client.leaderboard_scores_list_around_owner(session, request)
print(score_list)

Hiro 1.32 and earlier #

Prior to Hiro 1.33, leaderboards_config_get was the only way to retrieve available leaderboards, returning a LeaderboardConfigList with basic configuration data. This method is deprecated in Hiro 1.33 and later. Use leaderboard_list instead.

1
2
leaderboard_config_list = await hiro_client.leaderboards_config_get(session)
print(leaderboard_config_list)

Heroic Cloud