# Hiro Event Leaderboards Sample Project

**URL:** https://heroiclabs.com/docs/sample-projects/unity/hiro-event-leaderboards/
**Summary:** Cohort and tier-based competitive leaderboards for Unity games
**Keywords:** hiro leaderboards, event leaderboards, unity sdk, hiro coordinator, nakama system, nakama, cohort-based, tier-based
**Categories:** unity, sample-projects, hiro-event-leaderboards

---


## 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](../../../hiro/unity/getting-started/nakama-system/#hiro-deterministic-startup).

```csharp
// 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](../../../hiro/unity/getting-started/nakama-system)

### 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**

```csharp
// 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**

```csharp
// 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**

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

API reference: [Event Leaderboards](../../../hiro/unity/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.

```csharp
// 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](../../../hiro/concepts/event-leaderboards#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.