Hiro Challenges Sample Project

The official sample project for the Hiro Challenges system. This project demonstrates how to create, join, and manage challenges using the Hiro SDK in Unity. It’s built with minimal boilerplate so you can easily copy the code into your own game.

Features

• Challenge friends to different game modes, competing for the best score or time.
• Set rules like max score attempts, duration, and public/private visibility.
• Browse and join public challenges, invite friends to ongoing challenges, and view the status of active challenges.
• Submit scores and track rankings on real-time leaderboards.
• Claim rewards when a challenge ends.
• 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/
├── UnityHiroChallenges/
    ├── 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 (HiroChallengesCoordinator.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

// 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(HiroChallengesCoordinator), monitor, storage, logger);
    systems.Add(nakamaSystem);
    systems.Add(new ChallengesSystem(logger, nakamaSystem));
    // We need to register the EconomySystem to power rewards and the wallet
    systems.Add(new EconomySystem(logger, nakamaSystem, EconomyStoreType.Unspecified));
    return Task.FromResult(systems);
}

API reference: Hiro Initialization

Controller (ChallengesController.cs) #

Coordinates between the UI and Hiro Challenges API. Subscribes to view events, manages challenge state, and executes game logic by calling the Challenges system.

Challenge templates (game modes)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

// Load challenge templates, which are configured on the server
public async Task<List<string>> LoadChallengeTemplates()
{
    _challengeTemplates.Clear();
    var loadedTemplates = (await _challengesSystem.GetTemplatesAsync()).Templates;
    var challengeTemplateNames = new List<string>();

    foreach (var template in loadedTemplates)
    {
        _challengeTemplates[template.Key] = template.Value;
        challengeTemplateNames.Add(
            template.Value.AdditionalProperties.TryGetValue("display_name", out var displayName)
                ? displayName
                : template.Key);
    }

    return challengeTemplateNames;
}

Challenge discovery

1
2
3
4
5

// List challenges the user has joined or was invited to
var userChallengesResult = await _challengesSystem.ListChallengesAsync(null);

// Get detailed challenge info including participant scores (leaderboard)
var detailedChallenge = await _challengesSystem.GetChallengeAsync(challengeId, includeScores: true);

Challenge lifecycle

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

// Create a challenge from a template. Parameters defined separately
var newChallenge = await _challengesSystem.CreateChallengeAsync(
    selectedTemplate.Key,
    challengeName,
    description ?? "Missing description.",
    inviteeIDs,
    isOpen,
    selectedTemplate.Value.MaxNumScore,
    delay,
    duration,
    maxParticipants,
    category ?? "Missing category",
    new Dictionary<string, string>()
);

// Player actions
await _challengesSystem.JoinChallengeAsync(_selectedChallenge.Id);
await _challengesSystem.InviteChallengeAsync(_selectedChallenge.Id, userIds: inviteeIDs);
await _challengesSystem.LeaveChallengeAsync(_selectedChallenge.Id);
await _challengesSystem.ClaimChallengeAsync(_selectedChallenge.Id);

Scoring and rewards

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

// Submit a score with optional subscore and metadata
await _challengesSystem.SubmitChallengeScoreAsync(
    _selectedChallenge.Id,
    score,
    subScore,
    metadata,
    true
);

// Claim rewards when the challenge ends
await _challengesSystem.ClaimChallengeAsync(_selectedChallenge.Id);
await _economySystem.RefreshAsync();  // Update wallet UI with rewards

API reference: Challenges

Challenges view (ChallengesView.cs) #

Manages the main UI layer for the challenges screen, including lists, modals, and buttons. Provides an event-based interface that the controller subscribes to for responding to player interaction.

Challenge view (ChallengeView.cs) #

Binds challenge data to UI elements for the challenges list. Displays name, category, participant count, status (pending/active/ended), and end time.

Participant view (ChallengeParticipantView.cs) #

Binds participant score data to UI elements. Displays username, score, subscore, rank, and submission count (e.g., “2/3” means 2 scores submitted out of 3 allowed).

Account Switcher

The Account Switcher lets you explore the project as different players without managing multiple builds. Use it to view challenges, create challenges, and submit scores from different accounts.

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 Challenges concepts guide
• Hiro Unity SDK documentation
• Community forum