View as Markdown

Leaderboards

Read more about the Leaderboards system in Hiro here.

Initializing the leaderboards system #

The leaderboards system relies on the Nakama System and an ILogger, both must be passed in as dependencies via the constructor.

1
2

var leaderboardsSystem = new LeaderboardsSystem(logger, nakamaSystem);
systems.Add(leaderboardsSystem);

Getting the list of global leaderboard IDs #

Get a list of global leaderboard IDs from the local cache.

1

var leaderboardIds = leaderboardsSystem.GetLeaderboardIds();

Getting the list of regions for a leaderboard #

Get a list of regions for a specified leaderboard.

1

var leaderboardRegions = leaderboardsSystem.GetLeaderboardRegions("GalacticChampions");
The methods below require Hiro 1.33 or later. If you are on an earlier version, see Hiro 1.32 and earlier.

Refresh the leaderboard list #

Fetch and cache the full list of available leaderboards. Call this before listing or getting leaderboards.

1

await leaderboardsSystem.RefreshAsync();

List all leaderboards #

List all available leaderboards.

1

var leaderboards = await leaderboardsSystem.ListLeaderboardsAsync();

Filter by category:

1

var tournaments = await leaderboardsSystem.ListLeaderboardsAsync(new[] { "Tournament" });

Get a leaderboard #

Get a specified leaderboard by ID, including live timing data.

1

var leaderboard = await leaderboardsSystem.GetLeaderboardAsync("GalacticChampions");

Get scores #

For the current user #

1
2
3
4
5

// Global leaderboard
var score = await leaderboardsSystem.GetLeaderboardScoreAsync("GalacticChampions");

// Regional leaderboard
var score = await leaderboardsSystem.GetLeaderboardScoreAsync("GalacticChampions", "US");

For specific users #

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// Global leaderboard
var scores = await leaderboardsSystem.ListLeaderboardScoresAsync(
    id: "GalacticChampions",
    ownerIds: new[] { "userId1", "userId2" },
    limit: 100);

// Regional leaderboard
var scores = await leaderboardsSystem.ListLeaderboardScoresAsync(
    id: "GalacticChampions",
    ownerIds: new[] { "userId1", "userId2" },
    limit: 100,
    region: "EU");

For friends #

1
2

var friendsList = await nakamaSystem.Client.ListFriendsAsync(nakamaSystem.Session);
var scores = await leaderboardsSystem.ListLeaderboardScoresAsync("GalacticChampions", friendsList);

For a team #

1
2
3

var scores = await leaderboardsSystem.ListLeaderboardScoresAsync(
    id: "GalacticChampions",
    ownerIds: teamNakamaSystem.TeamMembers.Keys);

Around a user’s rank position #

Returns scores centred around a specific owner’s rank position, rather than the top of the leaderboard. Use this to show a player where they stand relative to their nearest competition: the players ranked just above and below them.

1
2
3
4

var scores = await leaderboardsSystem.ListLeaderboardScoresAroundOwnerAsync(
    id: "GalacticChampions",
    ownerId: session.UserId,
    limit: 10);

Submit a score #

Submit a score to a leaderboard.

1
2
3
4

var score = await leaderboardsSystem.UpdateLeaderboardScoreAsync(
    id: "GalacticChampions",
    score: 1500,
    subScore: 0);

Submit a score to a region-scoped leaderboard:

1
2
3
4
5

var score = await leaderboardsSystem.UpdateRegionLeaderboardScoreAsync(
    id: "GalacticChampions",
    region: "EU",
    score: 1500,
    subScore: 0);

Hiro 1.32 and earlier #

The following methods are deprecated in Hiro 1.33 and later.

Deprecated methodReplacement
WriteScoreAsyncUpdateLeaderboardScoreAsync
WriteRegionScoreAsyncUpdateRegionLeaderboardScoreAsync
GetRecordAsyncGetLeaderboardScoreAsync
GetRecordsAsyncListLeaderboardScoresAsync

Prior to Hiro 1.33, scores were submitted using WriteScoreAsync:

1

var record = await leaderboardsSystem.WriteScoreAsync("<leaderboardId>", score, subscore, metadata);

Scores were retrieved using GetRecordAsync and GetRecordsAsync:

1
2
3

var record = await leaderboardsSystem.GetRecordAsync("<leaderboardId>");

var records = await leaderboardsSystem.GetRecordsAsync("<leaderboardId>", new[] { "userId1", "userId2" });

Additional information #