Trophy Leaderboard in Magic Brick Wars by Halfbrick

Leaderboards

The Hiro Leaderboards system provides a unified API for competitive player rankings, built on top of Nakama Leaderboards. All leaderboard interactions go through Hiro’s personalizer, which means leaderboards can be created dynamically and personalized per user.

Hiro extends Nakama’s leaderboard capabilities with:

Regional leaderboards — automatically created for each configured ISO region code, so players compete within their own region as well as globally.
Tournament support — standard leaderboards and time-bounded tournaments share the same API surface. Setting a duration on a leaderboard definition creates it as a Nakama tournament.
Rich metadata — leaderboard definitions include name, description, category, and additional_properties, all returned to clients alongside live reset and timing data.
Friends leaderboards — filter scores by a list of owner IDs to display a friends leaderboard using Nakama’s Friends feature.

Configuration #

Leaderboard definitions are loaded from a JSON configuration file at startup. 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.


Property	Type	Description
`leaderboards`	`[]Leaderboard`	An array of all leaderboards.

Leaderboard parameters #

Each leaderboard in the leaderboards array may define the following parameters. Note a few parameters are availabe in Hiro 1.33 and later.


Property	Type	Description	Since
`id`	`string`	The ID of this leaderboard.
`name`	`string`	Display name for the leaderboard. May be an i18n key.	1.33
`description`	`string`	Description of the leaderboard. May be an i18n key.	1.33
`category`	`string`	Category used to group leaderboards together. Clients can filter by category when calling LeaderboardList.	1.33
`sort_order`	`string`	The leaderboard sort order: `asc` or `desc`. Cannot be used together with `ascending`.
`ascending`	`bool`	Alternative to `sort_order`. Set to `false` for descending order. Cannot be used together with `sort_order`.	1.33
`operator`	`string`	The score submission operator: `set`, `best`, `incr`, or `decr`.
`reset_schedule`	`string`	The reset schedule expressed in CRON format.
`authoritative`	`bool`	Whether scores must be submitted to this leaderboard authoritatively.
`regions`	`[]string`	ISO region codes for which regional leaderboards are created (for example, `EU`, `US`). A separate leaderboard is created for each region using the format `{id}-{region}`.
`start_time_sec`	`int64`	UNIX timestamp for the start of the tournament. Only applies to tournament leaderboards (those with `duration` set). Use `0` for no fixed start time.	1.33
`end_time_sec`	`int64`	UNIX timestamp for the end of the tournament. Only applies to tournament leaderboards. Use `0` for no fixed end time.	1.33
`duration`	`int64`	Duration of each tournament period in seconds. When set, Hiro creates the leaderboard as a Nakama tournament rather than a standard leaderboard.	1.33
`additional_properties`	`map<string, string>`	Arbitrary key-value metadata attached to the leaderboard and returned to clients.	1.33

Standard leaderboard cutomization parameters #

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
  "leaderboards": [
    {
      "id": "GalacticChampions",
      "name": "Galactic Champions", // Hiro 1.33 and later
      "description": "Compete to claim the Galactic Champion.", // Hiro 1.33 and later
      "category": "Leaderboard", // Hiro 1.33 and later
      "sort_order": "desc",
      "operator": "best",
      "reset_schedule": "0 0 */3 * *", // At 12:00 AM, every 3 days.
      "authoritative": true,
      "regions": ["EU", "US"],
      "additional_properties": {   // Hiro 1.33 and later
        "season": "Season 1",
        "banner_icon": "resources/leaderboards/galactic_champions_banner.png"
      }
    }
  ]
}

Tournament leaderboard cutomization parameters #

Setting duration causes Hiro to create the leaderboard as a Nakama tournament. Tournaments are time-bounded: each period runs for duration seconds and resets on the reset_schedule. Tournament is supported in Hiro 1.33 and later.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "leaderboards": [
    {
      "id": "CosmicWarriors",
      "name": "Cosmic Warriors", // Hiro 1.33 and later
      "description": "Battle opponents to earn your place among the elite.", // Hiro 1.33 and later
      "category": "Tournament", // Hiro 1.33 and later
      "ascending": false, // Hiro 1.33 and later
      "operator": "best",
      "reset_schedule": "0 0 * * *",
      "start_time_sec": 0, // Hiro 1.33 and later
      "end_time_sec": 0, // Hiro 1.33 and later
      "duration": 86400, // Hiro 1.33 and later. Setting `duration` creates a tournament.
      "authoritative": true,
      "regions": ["EU", "US"],
      "additional_properties": { // Hiro 1.33 and later
        "banner_icon": "resources/leaderboards/cosmic_warriors_banner.png"
      }
    }
  ]
}

Regional leaderboards #

When a leaderboard defines one or more regions, Hiro creates a separate leaderboard for each region at startup. The regional leaderboard ID uses the format {id}-{region} — for example, GalacticChampions-EU.

When submitting a score, include a region key in the score metadata to fan out the score to the corresponding regional leaderboard automatically.

Heroic Cloud