Install Hiro

Hiro is a game development kit that extends Nakama with powerful systems for economies, progression, social features, and more. This guide walks you through installing Hiro on your Nakama server and getting it running locally.

System requirements #

This guide assumes you’re running Nakama with Docker, which is the recommended approach for getting started quickly.

You’ll need:

Compatibility matrix #

Use the following table to find the required Nakama version for your Hiro release:

Hiro VersionNakama Version
1.29.03.34.1
1.28.03.32.0
1.27.13.32.0
1.26.03.30.0
1.25.03.28.0
1.24.03.27.1
1.23.03.27.0
1.22.03.26.0
1.21.03.25.0
1.20.03.24.2

Obtaining Hiro #

Hiro is available exclusively from Heroic Labs. Contact us to request access. We’ll provide you with:

  • Server binaries
  • Client SDKs
  • License key for your project
  • Access to dedicated engineering support

Install Hiro on the server #

Extract Hiro binaries #

After receiving your Hiro distribution archive (Hiro-<version>.zip), extract it to find the server binaries.

  1. Unzip the archive:
1
2

unzip Hiro-<version>.zip
cd Hiro-<version>/server
  1. Copy the binary files to your Nakama server directory:
1

cp hiro*.bin /path/to/your/nakama-project/

You should now have files like hiro-linux-arm64.bin, hiro-darwin-arm64.bin, etc. in your project directory.

Configure Docker #

Update your Docker configuration to copy Hiro binaries into your container and set up the recommended environment.

Update your Dockerfile #

Replace your existing Dockerfile with this configuration:

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

FROM heroiclabs/nakama-pluginbuilder:3.27.0 AS builder

ENV GO111MODULE on
ENV CGO_ENABLED 1

WORKDIR /backend
COPY . .

RUN go build --trimpath --buildmode=plugin -o ./backend.so

FROM heroiclabs/nakama:3.27.0

COPY --from=builder /backend/backend.so /nakama/data/modules
COPY --from=builder /backend/local.yml /nakama/data/
COPY --from=builder /backend/*.json /nakama/data/modules

# Copy Hiro binaries
COPY --from=builder /backend/hiro*.bin /nakama/data/modules

This Dockerfile builds your Go runtime as a plugin and copies both your code and the Hiro binaries into the Nakama container.

Update your docker-compose.yml #

Replace your existing docker-compose.yml with this recommended setup:

 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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

services:
  postgres:
    container_name: game_backend_postgres
    environment:
      - POSTGRES_DB=nakama
      - POSTGRES_PASSWORD=localdb
    expose:
      - "8080"
      - "5432"
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "postgres", "-d", "nakama"]
      interval: 3s
      timeout: 3s
      retries: 5
    image: postgres:12.2-alpine
    ports:
      - "5432:5432"
      - "8080:8080"
    volumes:
      - data:/var/lib/postgresql/data
  nakama:
    build: .
    container_name: game_backend
    depends_on:
      postgres:
        condition: service_healthy
    entrypoint:
      - "/bin/sh"
      - "-ecx"
      - >
        /nakama/nakama migrate up --database.address postgres:localdb@postgres:5432/nakama &&
        exec /nakama/nakama --config /nakama/data/local.yml --database.address postgres:localdb@postgres:5432/nakama        
    expose:
      - "7349"
      - "7350"
      - "7351"
    healthcheck:
      test: ["CMD", "/nakama/nakama", "healthcheck"]
      interval: 10s
      timeout: 5s
      retries: 5
    links:
      - "postgres:db"
    ports:
      - "7349:7349"
      - "7350:7350"
      - "7351:7351"
    restart: unless-stopped
volumes:
  data:

Set up your Go runtime #

Create your server-side code that initializes Hiro and configures which systems you want to use.

Add Hiro to your Go dependencies #

Run this command to add Hiro as a dependency:

1

go get github.com/heroiclabs/hiro@latest

Configure your license key #

Add your HIRO_LICENSE key to your local.yml config file:

1
2
3
4

runtime:
  env:
    - "ENV=dev1"
    - "HIRO_LICENSE=<your-license-key>"

Replace <your-license-key> with the license key provided by Heroic Labs.

Create your main.go file #

Your main.go file needs to initialize Hiro with your license key and configure which game systems you want to use. This code will:

  • Validate your license key from environment variables.
  • Detect your platform and select the correct Hiro binary.
  • Initialize Hiro with common game systems (base, inventory, economy, achievements, leaderboards, and stats).

Create a main.go file in your project root:

 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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

package main

import (
	"context"
	"database/sql"
	"errors"
	"fmt"
	osruntime "runtime"

	"github.com/heroiclabs/hiro"
	"github.com/heroiclabs/nakama-common/runtime"
)

//goland:noinspection GoUnusedExportedFunction
func InitModule(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, initializer runtime.Initializer) error {
	// Get environment variables from Nakama config
	props, ok := ctx.Value(runtime.RUNTIME_CTX_ENV).(map[string]string)
	if !ok {
		return errors.New("invalid context runtime env")
	}

	env, ok := props["ENV"]
	if !ok || env == "" {
		return errors.New("'ENV' key missing or invalid in env")
	}
	logger.Info("Using env named %q", env)

	hiroLicense, ok := props["HIRO_LICENSE"]
	if !ok || hiroLicense == "" {
		return errors.New("'HIRO_LICENSE' key missing or invalid in env")
	}

	// Select the correct binary for your platform
	binPath := "hiro.bin"
	switch osruntime.GOOS {
	case "darwin":
		switch osruntime.GOARCH {
		case "arm64":
			binPath = "hiro-darwin-arm64.bin"
		}
	case "linux":
		switch osruntime.GOARCH {
		case "arm64":
			binPath = "hiro-linux-arm64.bin"
		}
	}
	logger.Info("CPU os %q arch %q detected with binPath set as %q", osruntime.GOOS, osruntime.GOARCH, binPath)

	// Initialize Hiro with the systems you want to use
	systems, err := hiro.Init(ctx, logger, nk, initializer, binPath, hiroLicense,
		hiro.WithBaseSystem(fmt.Sprintf("base-system-%s.json", env), true),
		hiro.WithInventorySystem(fmt.Sprintf("base-inventory-%s.json", env), true),
		hiro.WithEconomySystem(fmt.Sprintf("base-economy-%s.json", env), true),
		hiro.WithAchievementsSystem(fmt.Sprintf("base-achievements-%s.json", env), true),
		hiro.WithLeaderboardsSystem(fmt.Sprintf("base-leaderboards-%s.json", env), true),
		hiro.WithStatsSystem(fmt.Sprintf("base-stats-%s.json", env), true))
	if err != nil {
		return err
	}
	_ = systems

	return nil
}

Create system config files #

Hiro systems are configured using JSON files. Create these files in your project root:

  • base-system-dev1.json
  • base-inventory-dev1.json
  • base-economy-dev1.json
  • base-achievements-dev1.json
  • base-leaderboards-dev1.json
  • base-stats-dev1.json

For now, create empty JSON objects in each file:

1
2
3
4
5
6

echo '{}' > base-system-dev1.json
echo '{}' > base-inventory-dev1.json
echo '{}' > base-economy-dev1.json
echo '{}' > base-achievements-dev1.json
echo '{}' > base-leaderboards-dev1.json
echo '{}' > base-stats-dev1.json

You’ll configure these files later based on your game’s requirements. See the individual system documentation for configuration options.

Download dependencies and build #

Install all Go dependencies:

1
2

go mod tidy
go mod vendor

Build and run your server with Docker Compose:

1

docker compose up --build

The first build takes a few minutes. Docker will:

  1. Build your Go plugin
  2. Create the Nakama container with your code and Hiro
  3. Start PostgreSQL
  4. Run database migrations
  5. Start Nakama

Verify installation #

You’ll know Hiro is installed correctly when you see logs like these:

1
2
3

game_backend | {"level":"info","ts":"2024-06-25T12:02:35.254Z","caller":"server/runtime.go:709","msg":"Registered Go runtime RPC function invocation","id":"rpc_id_base_set_device_prefs"}
game_backend | {"level":"info","ts":"2024-06-25T12:02:35.254Z","caller":"server/runtime.go:709","msg":"Registered Go runtime RPC function invocation","id":"rpc_id_inventory_grant"}
game_backend | {"level":"info","ts":"2024-06-25T12:02:35.254Z","caller":"server/runtime.go:709","msg":"Registered Go runtime RPC function invocation","id":"rpc_id_economy_donation_claim"}

These logs show that Hiro’s RPC functions are registered and ready to use.

Test your server is responding:

1

curl http://localhost:7350

You should see a JSON response with Nakama server information.

Install Hiro client SDKs #

After setting up Hiro on your server, you’ll need a client SDK to connect to it from your game. Hiro provides client SDKs for multiple platforms:

PlatformDescriptionDocumentation
UnityPackage containing DLLs for Unity projectsUnity client
UnrealPlugin for Unreal Engine with full C++ and Blueprint supportUnreal client
C++Cross-platform C++ library for custom enginesC++ client
TypeScriptTypeScript library for web and Node.jsTypeScript client
DartDart client library for Flutter and Dart applicationsDart client
GodotClient for Godot Engine projectsGodot client
PythonClient for Python projectsPython client

Post installation #

Upgrade Hiro #

To upgrade to a new version of Hiro:

  1. Download the new Hiro release from Heroic Labs.

  2. Replace the binary files in your server project:

    1

    cp Hiro-<new-version>/server/hiro*.bin /path/to/your/nakama-project/

  3. Update your Go dependency to match the server version:

    1

    go get github.com/heroiclabs/hiro@v<hiro-version>

  4. Check the version compatibility table in the System requirements section to see which Nakama version your new Hiro version requires

  5. Update your Dockerfile to use the matching Nakama version:

    1
2
3

    FROM heroiclabs/nakama-pluginbuilder:<nakama-version> AS builder
# ...
FROM heroiclabs/nakama:<nakama-version>

  6. Download updated dependencies:

    1

    go mod vendor

  7. Upgrade your client SDK to the matching version using the same installation process as before

  8. Rebuild and run your server:

    1

    docker compose up --build

Upgrade on Heroic Cloud #

If you’re using Heroic Cloud for hosting:

  1. Push your latest code to your repository.
  2. Go to your builder’s edit page in Heroic Cloud.
  3. Select the matching Nakama Image version from the dropdown.
  4. Click Update.
  5. Run a new container build.

Next steps #

Now that Hiro is installed, here’s what to do next:

Configure your game systems to populate the JSON configuration files with your game’s economy, achievements, and other system settings.

Explore sample projects for complete ready-to-run examples that demonstrate Hiro in action.