Hiro Event Leaderboards Sample Project

The official sample project for the Hiro Event Leaderboards system. See how to set up cohort-based competitions, handle tier progression, and manage the entire event leaderboard lifecycle. The code contains minimal boilerplate, so you can readily adapt it for your own project.

Features

• Browse and join active event leaderboards.
• Compete against a cohort of opponents matched by tier.
• Submit scores and track your ranking on the leaderboard.
• View promotion and demotion zones that determine tier changes.
• Claim rewards when the event ends.
• Built-in debug tools to fill leaderboards and randomize scores for testing.
• Built-in account switcher for quick multi-account testing.

Installation

The installation steps and resulting folder structure will vary depending on if you downloaded the project from Github or the Unity Asset Store.

The project connects to our demo server so you can see the features in action immediately.
Note: The server is reset on the 1st of every month at 00:00 UTC.

Folder structure

Assets/
├── UnityHiroEventLeaderboards/
    ├── HeroicUI/           # UI assets and styling
    ├── Scripts/            # Main project code
    ├── UI/                 # UI Builder files
    └── ...                 # Everything else
├── Packages/               # Contains the Nakama Unity package

Code overview #

The project uses Hiro’s systems-based architecture, which provides an opinionated structure for building games with pre-configured systems.

Coordinator (HiroEventLeaderboardsCoordinator.cs) #

Extends the HiroCoordinator class to set up the Nakama connection and initialize Hiro systems. It handles system lifecycle and authentication before your game logic runs. Learn more about Hiro’s deterministic startup.

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

// Create and register Hiro systems
protected override Task<Systems> CreateSystemsAsync()
{
    var client = new Client(scheme, host, port, serverKey);
    var nakamaSystem = new NakamaSystem(logger, client, NakamaAuthorizerFunc());

    var systems = new Systems(nameof(HiroEventLeaderboardsCoordinator), monitor, storage, logger);
    systems.Add(nakamaSystem);
    systems.Add(new EventLeaderboardsSystem(logger, nakamaSystem));
    // Register EconomySystem to power rewards and the wallet
    systems.Add(new EconomySystem(logger, nakamaSystem, EconomyStoreType.Unspecified));
    return Task.FromResult(systems);
}

API reference: Hiro Initialization

Controller (EventLeaderboardsController.cs) #

Coordinates between the UI and the Hiro Event Leaderboards API. Manages event leaderboard state, user actions, and debugging operations.

Listing and selecting event leaderboards

1
2
3
4
5

// List all available event leaderboards with scores
var eventLeaderboards = await _eventLeaderboardsSystem.ListEventLeaderboardsAsync(null, true);

// Get detailed event leaderboard with player scores
var detailedEventLeaderboard = await _eventLeaderboardsSystem.GetEventLeaderboardAsync(leaderboardId);

Submitting scores and claiming rewards

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// Submit a score with optional subscore
await _eventLeaderboardsSystem.UpdateEventLeaderboardAsync(
    leaderboardId,
    score,
    subScore
);

// Claim rewards when the event ends
await _eventLeaderboardsSystem.ClaimEventLeaderboardAsync(leaderboardId);
await _economySystem.RefreshAsync();  // Update wallet with rewards

Joining and re-rolling events

1
2

// Joins the event (or re-rolls with a new cohort after claiming)
await _eventLeaderboardsSystem.RollEventLeaderboardAsync(leaderboardId);

API reference: Event Leaderboards

Views #

The UI is split across three view classes:

• EventLeaderboardsView.cs: Main screen layout, event list, action buttons, and modals.
• EventLeaderboardView.cs: Individual event entry showing name, category, status, and time remaining.
• EventLeaderboardRecordView.cs: Player score card with username, score, and rank.

Promotion and demotion zones #

Event Leaderboards can advance or demote players between tiers using one of two methods: change zones (a percentage of top/bottom performers) or reward tiers (specific rank ranges). Both types of leaderboards are demonstrated in this project. In either case, zone boundaries are displayed to indicate which players are up for promotion or demotion. Two classes handle this:

• EventLeaderboardZoneView.cs: Renders zone indicators in the leaderboard UI.
• EventLeaderboardZoneCalculator.cs: Calculates zone boundaries from the event leaderboard config.

1
2
3
4
5

// Calculate zone boundaries from event configuration
var boundaries = EventLeaderboardZoneCalculator.CalculateZones(eventLeaderboard);

// Create display list with zone indicators inserted at correct positions
var displayItems = EventLeaderboardZoneCalculator.CreateDisplayList(scores, boundaries);

For more on how promotion and demotion work, see Player progression.

Time utility (EventLeaderboardTimeUtility.cs) #

Helper class for time-related calculations. Provides methods for determining time remaining, checking if an event has started, and formatting durations for display.

Account Switcher

The Account Switcher lets you explore the project as different players without managing multiple builds. Use it to join events as different accounts, submit scores from multiple players, and see how the leaderboard rankings update.

How to use:

1. Open the Account Switcher panel (Tools > Nakama > Account Switcher).
2. Select different accounts from the dropdown to switch between up to four test users.
3. Each account is automatically created the first time you select it.

Key points:

• Only works while your game is running in Play mode.
• Usernames will display in the panel after switching to an account for the first time.

Setting up your own Nakama server with Hiro

While this project works with our demo server, you'll want to set up your own Nakama and Hiro instance to customize the features and configurations.

Prerequisites

Before you can set up Hiro, you'll need to:

1. Install Nakama: Follow the Nakama installation guide to get Nakama running with Docker.
2. Obtain Hiro: Hiro is available to licensed users. Contact us to obtain your license.
3. Install Hiro: Once you have your license key, follow the Hiro installation guide.

Configure Hiro

This sample project ships with specific Hiro system configurations on the server. You can view the exact configuration files used in our demo server here: Demo server configurations.

Copy the JSON files to your server (such as inside a definitions directory) and update main.go to initialize the required Hiro systems according to the installation guide or view the example on Github.

Connect this Unity project to your server

After installing Nakama and Hiro and running it locally with the appropriate configurations, edit these settings in the Unity Editor to connect to your server:

1. Select the main coordinator component from the scene hierarchy panel.
2. Open the Inspector tab.
3. Look for the field inputs under Nakama Settings and replace them with the following:
   1. Scheme: http
   2. Host: 127.0.0.1
   3. Port: 7350
   4. Server Key: defaultkey

Additional resources

• Hiro Event Leaderboards concepts guide
• Hiro Unity SDK documentation
• Community forum