Skip to content
Gameye Gameye Gameye Docs

Integrating Nakama

Nakama is an open-source game backend by Heroic Labs. It handles player accounts, leaderboards, matchmaking, in-app purchases, and real-time multiplayer features.

Gameye provides a native Fleet Manager implementation for Nakama. When Nakama’s matchmaker finds a group of players, it calls the Gameye Fleet Manager, which starts a dedicated server session via the Session API. Nakama receives the IP and port and delivers them to the matched players — the entire flow runs without custom glue code.

How it works

Section titled “How it works”
[Nakama Matchmaker]
       ↓ match found
[Gameye Fleet Manager plugin]
       ↓ POST /session
[Gameye Session API]
       ↓ container starts (~0.5s)
[Dedicated game server] ←→ [Players]

The Fleet Manager handles the full session lifecycle: creation, player join and leave tracking, backfilling (adding players to existing sessions), and termination.

Prerequisites

Section titled “Prerequisites”
  • Nakama 3.21 or later
  • A Gameye API token (request sandbox access)
  • Your game server Docker image registered with Gameye (handled during onboarding)
  • Go 1.21+ in your Nakama server module’s build environment

Installation

Section titled “Installation”

Add the Fleet Manager package to your Nakama server module:

Terminal window
go get github.com/Gameye/nakama-fleetmanager/fleetmanager

Update your go.mod:

require (
    github.com/heroiclabs/nakama-common v1.32.0
    github.com/Gameye/nakama-fleetmanager v1.0.0
)

Configuration

Section titled “Configuration”

Five environment variables configure the Fleet Manager. Set them on the process that runs your Nakama server:

VariableDescription
GAMEYE_API_TOKENYour Gameye API authentication token
GAMEYE_API_URLYour Gameye environment URL (provided during onboarding)
GAMEYE_API_IMAGEYour application name in Gameye
GAMEYE_API_IMAGE_VERSIONThe specific image tag/version to deploy
GAMEYE_API_REGIONTarget region name (e.g. europe, us-east)

Docker Compose example

Section titled “Docker Compose example”
services:
  nakama:
    image: heroiclabs/nakama:3.22.0
    environment:
      GAMEYE_API_TOKEN: "your-api-token"
      GAMEYE_API_URL: "https://api.gameye.io"
      GAMEYE_API_IMAGE: "your-image-name"
      GAMEYE_API_IMAGE_VERSION: "1.0.0"
      GAMEYE_API_REGION: "europe"
    volumes:
      - ./nakama-modules:/nakama/data/modules

Registration in InitModule

Section titled “Registration in InitModule”

Register the Fleet Manager in your Nakama server module’s InitModule function. See the nakama-fleetmanager README on GitHub for the current registration code and constructor signature.

The pattern follows Heroic Labs’ own GameLift Fleet Manager implementation — fleetmanager.New(config) returns an object that satisfies Nakama’s runtime.FleetManager interface, which you pass to initializer.RegisterFleetManager().

Using with Unity Matchmaker

Section titled “Using with Unity Matchmaker”

If you’re using Unity Matchmaker alongside Nakama, allocations can be routed to Gameye without changing your matchmaking rules or ticket logic. For a dedicated Unity Matchmaker integration that does not require Nakama, see the Unity Matchmaker guide.

Known limitations

Section titled “Known limitations”
  • Limited session list querying — Gameye’s Session API does not paginate, which limits FleetManager#List for studios that need to query large numbers of running sessions programmatically.
  • No built-in retry queue — Sessions are created immediately on request. If session creation fails, retry logic must be handled at the application layer.

Further reading

Section titled “Further reading”