Hiro Store Sample Project

The official sample project for the Hiro Economy system. This project demonstrates how to build a virtual store with the Hiro Economy system. It pulls items from the economy configuration, filters by category, validates purchase attempts, and keeps the wallet in sync. The sample also shows how to handle guaranteed rewards and weighted (loot box–style) drops. It’s built with minimal boilerplate so you can easily copy the code into your own game.

Features

• Pull the economy catalog, filter items by category (currency or items), and surface featured items from item metadata.
• Refresh the store catalog and wallet together so prices and balances stay current.
• Execute purchases through EconomySystem, then refresh economy state to reflect new balances and ownership.
• Handle rewards from purchases, including guaranteed currency and item grants, plus weighted (loot box–style) drops.

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/
├── UnityHiroStore/
    ├── 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 (HiroStoreCoordinator.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. For details, see Hiro’s deterministic startup.

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

protected override Task<Systems> CreateSystemsAsync() {
    var logger = new Hiro.Unity.Logger();
    var monitor = NetworkMonitor.Default;
    var client = localHost
        ? new Client("http", "127.0.0.1", 7350, "defaultkey")
        : new Client(scheme, host, port, serverKey);
    var nakamaSystem = new NakamaSystem(logger, client, NakamaAuthorizerFunc());

    var storage = MemoryStorage.Default;

    // Register necessary Hiro Systems
    var systems = new Systems(nameof(HiroStoreCoordinator), monitor, storage, logger);
    systems.Add(nakamaSystem);
    var economySystem = new EconomySystem(logger, nakamaSystem, EconomyStoreType.Unspecified);
    systems.Add(economySystem);

    return Task.FromResult(systems);
}

API reference: Hiro Initialization

Controller (StoreController.cs) #

Coordinates between the store UI and the Hiro Economy. Subscribes to init and view events, maintains the catalog, wallet, and item cache, and executes purchases through EconomySystem with affordability checks and state refresh.

Store operations #

Refresh store

Pull latest store data, cache items, and refresh the UI.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

public async Task RefreshStore()
{
    try
    {
        await _economySystem.RefreshStoreAsync();
        await _economySystem.RefreshAsync();

        StoreItems.Clear();
        StoreItems.AddRange(_economySystem.StoreItems);

        Debug.Log($"Loaded {StoreItems.Count} store items");

        // Find featured item for Featured tab
        _featuredItem = (EconomyListStoreItem)StoreItems.FirstOrDefault(item => 
            item.Category == "featured" || item.Name.ToLower().Contains("starter"));

        // Find lootbox item for Deals tab
        _lootboxItem = (EconomyListStoreItem)StoreItems.FirstOrDefault(item => 
            item.Category == "lootbox" || item.Name.ToLower().Contains("lootbox") || 
            item.Name.ToLower().Contains("mystery"));

        await _view.RefreshStoreDisplay();
    }
    catch (Exception e)
    {
        Debug.LogException(e);
        _view.ShowError($"Failed to refresh store: {e.Message}");
    }
}

Purchase operations #

Purchase item

Attempt a purchase by item ID, refresh economy data on success, and bubble up errors.

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

public async Task<IEconomyPurchaseAck> PurchaseItem(IEconomyListStoreItem item)
{
    if (item == null)
        throw new Exception("No item selected");

    try
    {
        IEconomyPurchaseAck result;
        result = await _economySystem.PurchaseStoreItemAsync(item.Id);
        Debug.Log($"Purchased {item.Name} successfully");

        // Refresh economy
        await _economySystem.RefreshAsync();

        return result;
    }
    catch (Exception e)
    {
        Debug.LogError($"Purchase failed: {e.Message}");
        throw;
    }
}

Additional operations #

Can afford item

Check wallet balances against all currency costs for an item.

API reference: Store

Views #

StoreView

Main store screen wiring tabs, wallet, featured item, grid population, and purchase/reward/error modals.

StoreItemView

Single store item tile showing icon, amount/name, badges, price/currency, and purchase button behavior.

CodexItemView

Codex entry display for inventory items with name, description fallback, category, and consumable flag.

Account Switcher

The Account Switcher lets you explore the project as different players without managing multiple builds. Use it to test features 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 Store concepts guide
• Hiro Unity SDK documentation
• Community forum