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