# Leaderboards

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

---


<figure class="float-right" style="max-width: 35%; border: 20px solid transparent; text-align: center;">
  <img 
    src="{{< fingerprint_image "/images/pages/hiro/concepts/leaderboards/leaderboards-magicbrickwars.png" >}}" 
    style="width: 100%;"
  >
  <figcaption> Trophy Leaderboard in Magic Brick Wars by Halfbrick </figcaption>
</figure>

# Leaderboards

Leaderboards are a common feature in games to provide engagement and competitiveness among your player base, and Nakama provides a feature-rich implementation of [Leaderboards](../../../nakama/concepts/leaderboards/). The Hiro wraps the features and functionality of the Nakama leaderboards system, and adds: built-in support for regional leaderboards, identified by their ISO Code, convenient display for friends leaderboards (using Nakama's [Friends](../../../nakama/concepts/friends/) feature), and a convenient way to fan-out score updates to multiple leaderboards.

{{< note "info" >}}
Please refer to Nakama's [Leaderboards](../../../nakama/concepts/leaderboards/) documentation for the full information about the system. 
{{< /note >}}

## Customization parameters

The following JSON represents the customization parameters you can use to configure the default user experience for the leaderboard system.

```json
{
  "leaderboards": [{
      "id": "chef-tournament",
      "sort_order": "desc",
      "operator": "set",
      "reset_schedule": "0 0 */3 * *", // At 12:00 AM, every 3 days.
      "authoritative": true,
      "regions": [
        "EU",
        "US"
      ]
  }]
}
```

The JSON schema defines a `leaderboards` array which _must contain individual objects for each leaderboard_ you wish to define in the system. You can configure as few or as many leaderboards as needed for your desired gameplay.

{{< table name="gdk.concepts.leaderboards.leaderboards-system">}}

Each individual leaderboard may define the following:

### Leaderboard

{{< table name="gdk.concepts.leaderboards.leaderboard">}}

## Additional Information

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