Installing Hiro #

Prerequisites #

Before proceeding ensure that you have:

Server #

  1. We will provide you with an archive in the format Hiro-"<version>".zip. Un-zip and enter the server folder to find the Hiro binaries.

  2. Take the binary files and place them into your Nakama server’s directory.

  3. Update your docker-compose.yml to use our recommended setup for Hiro:

 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
version: '3.9'
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:
  1. Update your Dockerfile to copy the Hiro binaries to the correct directory when setting up your Docker container:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
FROM heroiclabs/nakama-pluginbuilder:3.22.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.22.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

# Add these lines below:
COPY --from=builder /backend/hiro.bin /nakama/data/modules
COPY --from=builder /backend/hiro-dsym.bin /nakama/data/modules
  1. Add your HIRO_LICENSE key to your local.yml config.
1
2
3
4
runtime:
    env:
    - "ENV=dev1"
    - "HIRO_LICENSE=<license-here>"
  1. Run this command to add Hiro as dependency:
go get "github.com/heroiclabs/hiro@latest"
  1. Create a main.go file in the root of your project and add the following boilerplate code that will initialize Hiro and allow you to register the modules that you need for your game:
 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
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 {
	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")
	}

	binPath := "hiro.bin"
	switch osruntime.GOOS {
	case "darwin":
		switch osruntime.GOARCH {
		case "arm64":
			binPath = "hiro-darwin-arm64.bin"
		}
	}
	logger.Info("CPU os %q arch %q detected with binPath set as %q", osruntime.GOOS, osruntime.GOARCH, binPath)

	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
}
  1. Run this command to make sure that all dependencies are downloaded:
go mod vendor
  1. Finally, build and run your project:
docker compose up --build
  1. You should now see many logs that look similar to this, confirming that Hiro’s RPC functions have been registered:
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"}

Upgrading Hiro #

To upgrade Hiro on the server-side:

  1. Download the Hiro release that you would like to upgrade to and replace the binaries in your server project.

  2. Use the “go get” subcommand to download the same Hiro version in your Go code:

go get "github.com/heroiclabs/hiro@v<hiro-version>"
  1. Check the Hiro compatibility matrix to see which Nakama version is depended on by your new version of Hiro.

  2. Open your Dockerfile and update any references from your previous Nakama version to the new version found in the previous step.

  3. Run this command to download the latest versions of your dependencies.

go mod vendor
  1. Finally, upgrade your client-side Hiro package to the same version being used on the server-side. All you will need to do is follow the same steps as you did when initially setting up Hiro, simply replacing your old Hiro package with the updated one.

Heroic Cloud #

If you wish to upgrade your Heroic Cloud deployment, then continue following these next steps, otherwise you can stop here and run your server locally as you usually would.

  1. Add the previous changes you have made to your project’s repository.

  2. Go to your builder’s edit page and select the same Namaka Image version as you have used in your Dockerfile, then press update.

  3. Run a container build with your cloud builder.

Clients #

The clients are available from Heroic Labs. Contact us to request access.

Unity

Check out our Unity Client.

Unreal

Check out our Unreal Client.

C++

Check out our C++ Client.

Typescript

Check out our Typescript Client.

Compatibility Matrix #

Hiro VersionNakama Version
1.20.03.24.2
1.19.03.23.0
1.18.03.23.0
1.17.03.23.0
1.16.03.22.0
1.15.03.22.0
1.14.03.22.0
1.13.03.21.1
1.12.03.21.1
1.11.03.21.1
1.10.03.21.1
1.9.03.20.1
1.8.13.20.1
1.8.03.20.1
1.7.03.17.1
1.6.03.17.1
1.5.03.17.1
1.4.03.17.1
1.3.03.17.1
1.2.03.17.1
1.1.03.17.0
1.0.43.17.0
1.0.33.17.0
1.0.23.16.0
1.0.13.16.0
1.0.03.16.0