# Leaderboards

**URL:** https://heroiclabs.com/docs/hiro/unity/leaderboards/
**Keywords:** leaderboards, hiro
**Categories:** hiro, unity, leaderboards

---


# Leaderboards

Read more about the Leaderboards system in Hiro [here](../../concepts/leaderboards/).

## Initializing the leaderboards system

The leaderboards system system relies on the [Nakama System](../getting-started/nakama-system) and an `ILogger`, both must be passed in as dependencies via the constructor.

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

## Getting leaderboard records

You can get the user's own cached record for a specific leaderboard.

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

You can also optionally specify a region ID to get the region specific score.

```csharp
var usRecord = leaderboardsSystem.GetRecordAsync("<leaderboardId>", "US");
```

## Getting leaderboard records for specific users

You can get leaderboard records for a specific set of users, by providing either an array of user Ids, a list of friends or a Team (as defined in the `TeamNakamaSystem`).

For specific users:

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

For friends:

```csharp
var friendsList = await nakamaSystem.Client.ListFriendsAsync(nakamaSystem.Session);
var records = await leaderboardsSystem.GetRecordsAsync("<leaderboardId>", friendsList);
```

You can also specify the region to retrieve records for:

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

## Getting the list of global leaderboard IDs

You can get a list of global leaderboard IDs.

```csharp
var leaderboardIds = leaderboardsSystem.GetLeaderboardIds();
```

## Getting the list of regional for a leaderboard

You can get a list of regions for a specified leaderboard.

```csharp
var leaderboardRegions = leaderboardsSystem.GetLeaderboardRegions("<leaderboardId>");
```

## Submitting a leaderboard score

You can submit a leaderboard score for the user.

```csharp
var score = 100;
var subscore = 10;
var metadata = "<metadataJson>";

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

## Additional information

- [Nakama Leaderboards sample project](../../../sample-projects/unity/nakama-leaderboards)
- [Mage Mayhem sample project](../../../sample-projects/games/mage-mayhem)