Nakama

https://heroiclabs.com/docs/nakama
Admin
Nakama is an open-source server framework for building multiplayer games with features including...
Tokens:1,131,267
Snippets:11,655
Trust Score:9.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example Call to Start Matchmaking

Source: https://heroiclabs.com/docs/nakama/tutorials/godot/fishgame/llm.md

Demonstrates how to call OnlineMatch.start_matchmaking() with specific matchmaking criteria, including player count, string properties, and a custom query.

```gdscript
OnlineMatch.start_matchmaking(Online.nakama_socket, {
  # The default minimum is 2, we can increase that to 3 to find a 3-player match.
  min_count = 3,

  # We can tell the matchmaker about string or numeric properties of this player.
  string_properties = {
    region = 'europe',
  },
  numeric_properties = {
    rank = 8,
  },

  # The query requires a player in the same region and similar rank.
  query = '+region:europe +rank:>=7 +rank:<=9'
})
```

--------------------------------

### Start CockroachDB (Command Prompt)

Source: https://heroiclabs.com/docs/nakama/getting-started/install/windows/index.html

Starts a single-node CockroachDB instance in insecure mode on localhost. Use this for initial setup and local development.

```bash
cockroach.exe start-single-node --insecure --listen-addr=127.0.0.1
```

--------------------------------

### Start CockroachDB (Powershell/Bash)

Source: https://heroiclabs.com/docs/nakama/getting-started/install/windows/index.html

Starts a single-node CockroachDB instance in insecure mode on localhost. Use this for initial setup and local development.

```bash
./cockroach.exe start-single-node --insecure --listen-addr=127.0.0.1
```

--------------------------------

### Enable and Start Nakama systemd Service

Source: https://heroiclabs.com/docs/nakama/getting-started/install/linux/llm.md

Enable the Nakama service to start on boot and then start the service immediately.

```sh
sudo systemctl enable nakama
sudo systemctl start nakama
```

--------------------------------

### Install Docker and Docker Compose

Source: https://heroiclabs.com/docs/nakama/guides/deployment/digital-ocean/index.html

Download and execute the official Docker installation script on your Ubuntu droplet.

```bash
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
```

--------------------------------

### JavaScript runtime entry point example

Source: https://heroiclabs.com/docs/nakama/server-framework/introduction/index.html

A simple numeric entry point example for the JavaScript runtime.

```text
1
```

--------------------------------

### List Ready Instances Query Example

Source: https://heroiclabs.com/docs/nakama/guides/concepts/edgegap-integration/index.html

Example query for instance_list to find instances that are READY and have at least one seat available.

```json
{
  "query": "+value.metadata.edgegap.available_seats:>=1 +value.status:READY",
  "limit": 100,
  "cursor": ""
}
```

--------------------------------

### LeaderboardCreate Example

Source: https://heroiclabs.com/docs/nakama/server-framework/go-runtime/function-reference

Creates a new dynamic leaderboard with specified configuration settings. The example demonstrates setting the ID, sort order, operator, reset schedule, metadata, and rank enablement.

```go
id := "4ec4f126-3f9d-11e7-84ef-b7c182b36521"
authoritative := false
sortOrder := "desc"
operator := "best"
resetSchedule := "0 0 * * 1"
metadata := map[string]interface{}{
	"weather_conditions": "rain",
}
enableRanks = false // Set to true to enable rank computation on leaderboard records.

if err := nk.LeaderboardCreate(ctx, id, authoritative, sortOrder, operator, resetSchedule, metadata, enableRanks); err != nil {
	logger.WithField("err", err).Error("Leaderboard create error.")
}
```

--------------------------------

### Start Nakama Server

Source: https://heroiclabs.com/docs/nakama/getting-started/commands/index.html

Starts the Nakama server with default configuration. Command line flags can override default and configuration file parameters.

```bash
nakama
```

--------------------------------

### Install the i3D fleet manager module

Source: https://heroiclabs.com/docs/nakama/guides/concepts/i3d-integration/index.html

Use the go get command to add the i3D fleet manager dependency to your Nakama Go project.

```bash
go get github.com/i3d/nakama-fleetmanager
```

--------------------------------

### Start Nakama Server with PostgreSQL

Source: https://heroiclabs.com/docs/nakama/getting-started/install/linux/llm.md

Start the Nakama server with PostgreSQL, providing the same database connection string used for migrations. The database must be running prior to this.

```sh
./nakama --database.address postgres:password@127.0.0.1:5432
```

--------------------------------

### Start Nakama with Docker Compose

Source: https://heroiclabs.com/docs/nakama/getting-started/install/docker/llm.md

Pull the required container images and start the Nakama server and database services.

```sh
docker compose up
```

--------------------------------

### Initialize NPM and Install TypeScript

Source: https://heroiclabs.com/docs/nakama/server-framework/typescript-runtime/llm.md

Initializes a new Node.js project using NPM and installs the TypeScript compiler as a development dependency.

```bash
npm init -y
npm install --save-dev typescript
```

--------------------------------

### Install Nakama-GameLift Plugin

Source: https://heroiclabs.com/docs/nakama/guides/concepts/gamelift-integration/index.html

Run this command in your Nakama project folder to install the plugin dependency.

```bash
go get github.com/heroiclabs/nakama-gamelift/fleetmanager
```

--------------------------------

### Query Game Sessions Example

Source: https://heroiclabs.com/docs/nakama/guides/concepts/gamelift-integration/index.html

An example query searching for game sessions with a specific name prefix and game mode.

```go
query := "+values.metadata.GameSessionName:/(season).+/ +values.metadata.GameProperties.mode:freeforall"
```

--------------------------------

### Install Nakama Runtime Package

Source: https://heroiclabs.com/docs/nakama/server-framework/typescript-runtime/llm.md

Installs a specific version of the nakama-runtime package from GitHub. Replace `<version>` with the desired GitHub tag.

```bash
npm i https://github.com/heroiclabs/nakama-common#<version>
```

--------------------------------

### Setup Nakama RealtimeClient

Source: https://heroiclabs.com/docs/nakama/client-libraries/unreal/index.html

Create a real-time client from the main Nakama client and connect it using success and error delegates.

```cpp
RealtimeClient = Client->SetupRealtimeClient(Session);

FOnRealtimeClientConnected ConnectionSuccessDelegate;
ConnectionSuccessDelegate.AddDynamic(this, &ASagiShiActor::OnRealtimeClientConnectionSuccess);

FOnRealtimeClientError ConnectionErrorDelegate;
ConnectionErrorDelegate.AddDynamic(this, &ASagiShiActor::OnRealtimeClientConnectionError);

RealtimeClient->Connect(ConnectionSuccessDelegate, ConnectionErrorDelegate);

/* Define callbacks */

void ASagiShiActor::OnRealtimeClientConnectionSuccess()
{
    UE_LOG(LogTemp, Log, TEXT("Socket connection succeeded."));
}

void ASagiShiActor::OnRealtimeClientConnectionError()
{
    UE_LOG(LogTemp, Log, TEXT("Socket connection failed."));
}
```

--------------------------------

### Initialize Go module and install Nakama runtime

Source: https://heroiclabs.com/docs/nakama/server-framework/go-runtime/index.html

Commands to initialize the Go module and fetch the Nakama runtime package.

```bash
go mod init example.com/go-project
go get github.com/heroiclabs/nakama-common/runtime
```

--------------------------------

### Define Army Setup Variable

Source: https://heroiclabs.com/docs/nakama/concepts/storage/permissions

A simple variable definition used in various client examples.

```javascript
var army_setup = "{ \"soldiers\": 50 }";
```

--------------------------------

### List Notifications REST API

Source: https://heroiclabs.com/docs/nakama/concepts/notifications/llm.md

Example of an HTTP GET request to list notifications, including limit and cursor parameters.

```shell
GET /v2/notification?limit=100&cursor=<cacheableCursor>
Host: 127.0.0.1:7350
Accept: application/json
Content-Type: application/json
Authorization: Bearer <session token>
```

--------------------------------

### Initialize User on Registration (Go)

Source: https://heroiclabs.com/docs/nakama/server-framework/runtime-examples/llm.md

This Go example demonstrates initializing a new user by adding currency to their wallet after authentication, using the 'AfterAuthenticateDevice' hook.

```go
func InitializeUser(ctx context.Context, logger Logger, db *sql.DB, nk NakamaModule, out *api.Session, in *api.AuthenticateDeviceRequest) error {
  if out.Created {
    // Only run this logic if the account that has authenticated is new.
    userID, ok := ctx.Value(runtime.RUNTIME_CTX_USER_ID).(string)
    if !ok {
      return "", errors.New("Invalid context")
    }
    changeset := map[string]interface{}{
      "coins": 10,    // Add 10 coins to the user's wallet.
      "gems":  5,     // Add 5 gems to the user's wallet.
      "artifacts": 0, // No artifacts to start with.
    }
    var metadata map[string]interface{}
    if err := nk.WalletUpdate(ctx, userID, changeset, metadata, true); err != nil {
      // Handle error.
    }
  }
}

// Register as after hook, this call should be in InitModule.
if err := initializer.RegisterAfterAuthenticateDevice(InitializeUser); err != nil {
  logger.Error("Unable to register: %v", err)
  return err
}
```

--------------------------------

### Get Account with Blocking Call

Source: https://heroiclabs.com/docs/nakama/client-libraries/java/llm.md

Retrieves an account for a given session using a blocking call. This is a simplified example for brevity.

```java
Account account = client.getAccount(session).get();
```

--------------------------------

### Server Startup Log Output

Source: https://heroiclabs.com/docs/nakama/server-framework/go-runtime/index.html

Example log output confirming that the Go runtime has successfully loaded and executed the custom code.

```json
{
  "level": "info",
  "ts": "....",
  "caller": "go-project/main.go:10",
  "msg": "Hello World!",
  "runtime": "go"
}
```

--------------------------------

### List groups REST API request

Source: https://heroiclabs.com/docs/nakama/concepts/groups/index.html

Example of a GET request to the Nakama REST API to list groups with a limit and cursor.

```http
GET /v2/group?limit=20&name=heroes%&cursor=somecursor
Host: 127.0.0.1:7350
Accept: application/json
Content-Type: application/json
Authorization: Bearer <session token>
```

--------------------------------

### Correct Caching Pattern

Source: https://heroiclabs.com/docs/nakama/server-framework/introduction/best-practices/index.html

This example demonstrates loading static data once at module initialization into a package-level variable for efficient access.

```go
var itemDefs map[string]ItemDef // loaded once, read-only afterwards

func InitModule(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, initializer runtime.Initializer) error {
	data, err := os.ReadFile("data/item_definitions.json")
	if err != nil {
		return err // fail fast at startup, not per request
	}
	if err := json.Unmarshal(data, &itemDefs); err != nil {
		return err
	}
	// ...
}

func RpcGetItemInfo(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, payload string) (string, error) {
	item, ok := itemDefs[payload]
	// ...
```

--------------------------------

### Full rpc-add-item.test.ts example

Source: https://heroiclabs.com/docs/nakama/guides/server-framework/typescript-testing/index.html

A complete test file setup using ts-auto-mock and Jest to test various success and failure scenarios for an RPC function.

```typescript
import { createMock } from 'ts-auto-mock';
import { On, method } from 'ts-auto-mock/extension';
import AddItemRpc from "./rpc-add-item";
import { describe, expect, beforeEach, test } from '@jest/globals';

describe('AddItemRpc', function () {
    let mockCtx: any, mockLogger: any, mockNk: any, mockLoggerError: any, mockNkStorageRead: any, mockNkStorageWrite: any, mockStorageWriteAck: any;

  beforeEach(function () {
    mockCtx = createMock<nkruntime.Context>({ userId: 'mock-user' });
    mockLogger = createMock<nkruntime.Logger>();
    mockNk = createMock<nkruntime.Nakama>();
    mockStorageWriteAck = createMock<nkruntime.StorageWriteAck>();
    mockLoggerError = On(mockLogger).get(method(function (mock) {
      return mock.error;
    }))
    mockNkStorageRead = On(mockNk).get(method(function (mock) {
      return mock.storageRead;
    }));
    mockNkStorageWrite = On(mockNk).get(method(function (mock) {
      return mock.storageWrite;
    }));
  });

  test('returns failure if payload is null', function () {
    const payload = null;
    const result = AddItemRpc(mockCtx, mockLogger, mockNk, payload);
    const resultPayload = JSON.parse(result);
    const expectedError = 'no payload provided';


    expect(resultPayload.success).toBe(false);
    expect(resultPayload.error).toBe(expectedError);
    expect(mockLoggerError).toBeCalledWith(expectedError);
  });

  test('returns failure if payload is empty string', function () {
    const payload = "";
    const result = AddItemRpc(mockCtx, mockLogger, mockNk, payload);
    const resultPayload = JSON.parse(result);
    const expectedError = 'no payload provided';
```

--------------------------------

### List tournament records around owner via REST API

Source: https://heroiclabs.com/docs/nakama/concepts/tournaments/index.html

Example HTTP GET request to fetch tournament records around a specific owner.

```http
GET /v2/tournament/<tournament_id>/owner/<owner_id>?limit=<limit>
Host: 127.0.0.1:7350
Accept: application/json
Content-Type: application/json
Authorization: Bearer <session token>
```

--------------------------------

### Store Match State in TypeScript

Source: https://heroiclabs.com/docs/nakama/concepts/multiplayer/authoritative/index.html

This TypeScript example shows how to initialize match state and update the 'started' flag within the match loop based on presence count.

```typescript
const matchInit = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, params: {[key: string]: string}): {state: nkruntime.MatchState, tickRate: number, label: string} {
  return {
    state: { presences: {}, started: false },
    tickRate,
    label: ''
  };
};

const matchLoop = function (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, dispatcher: nkruntime.MatchDispatcher, tick: number, state: nkruntime.MatchState, messages: nkruntime.MatchMessage[]) : { state: nkruntime.MatchState} | null {
   if (state.presences.length > 2) {
    state.started = true;
  }

  return {
    state
  };
}
```

--------------------------------

### Initialize User with Go

Source: https://heroiclabs.com/docs/nakama/server-framework/runtime-examples/index.html

Registers an after hook in InitModule to update the wallet for newly created accounts.

```go
func InitializeUser(ctx context.Context, logger Logger, db *sql.DB, nk NakamaModule, out *api.Session, in *api.AuthenticateDeviceRequest) error {
  if out.Created {
    // Only run this logic if the account that has authenticated is new.
    userID, ok := ctx.Value(runtime.RUNTIME_CTX_USER_ID).(string)
    if !ok {
      return "", errors.New("Invalid context")
    }
    changeset := map[string]interface{}{
      "coins": 10,    // Add 10 coins to the user's wallet.
      "gems":  5,     // Add 5 gems to the user's wallet.
      "artifacts": 0, // No artifacts to start with.
    }
    var metadata map[string]interface{}
    if err := nk.WalletUpdate(ctx, userID, changeset, metadata, true); err != nil {
      // Handle error.
    }
  }
}

// Register as after hook, this call should be in InitModule.
if err := initializer.RegisterAfterAuthenticateDevice(InitializeUser); err != nil {
  logger.Error("Unable to register: %v", err)
  return err
}
```

--------------------------------

### List Leaderboard Records by Owner IDs (HTTP Request)

Source: https://heroiclabs.com/docs/nakama/concepts/leaderboards/llm.md

Example of an HTTP GET request to list leaderboard records filtered by owner IDs. Ensure the Authorization header is correctly set.

```shell
GET /v2/leaderboard/<leaderboardId>?owner_ids=some&owner_ids=friends
Host: 127.0.0.1:7350
Accept: application/json
Content-Type: application/json
Authorization: Bearer <session token>
```

--------------------------------

### Initialize Game Setup in Godot

Source: https://heroiclabs.com/docs/nakama/tutorials/godot/fishgame/llm.md

This function pauses the game, sets up player instances, and synchronizes initial game state across clients. It's called to prepare the game before the match starts.

```gdscript
remotesync func _do_game_setup(players: Dictionary) -> void:
	get_tree().set_pause(true)

	if game_started:
		game_stop()

	game_started = true
	game_over = false
	players_alive = players

	reload_map()

	var player_number := 1
	for peer_id in players:
		var other_player = Player.instance()
		other_player.name = str(peer_id)
		players_node.add_child(other_player)

		other_player.set_network_master(peer_id)
		other_player.set_player_skin(player_number - 1)
		other_player.set_player_name(players[peer_id])
		other_player.position = map.get_node("PlayerStartPositions/Player" + str(player_number)).position
		other_player.rotation = map.get_node("PlayerStartPositions/Player" + str(player_number)).rotation
		other_player.connect("player_dead", self, "_on_player_dead", [peer_id])

		if not GameState.online_play:
			other_player.player_controlled = true
			other_player.input_prefix = "player" + str(player_number) + "_"

		player_number += 1

	camera.update_position_and_zoom(false)

	if GameState.online_play:
		var my_id := get_tree().get_network_unique_id()
		var my_player := players_node.get_node(str(my_id))
		my_player.player_controlled = true

		# Tell the host that we've finished setup.
		rpc_id(1, '_finished_game_setup', my_id)
	else:
		_do_game_start()

```

--------------------------------

### Initialize Nakama Defold Client

Source: https://heroiclabs.com/docs/nakama/concepts/authentication/index.html

Initializes the Defold client using a configuration table.

```lua
local defold = require "nakama.engine.defold"

local config = {}
config.host = 127.0.0.1
config.port = 7350
config.use_ssl = false
config.username = "defaultkey"
config.engine = defold

local client = nakama.create_client(config)
```

--------------------------------

### Get or Create Device ID in C#

Source: https://heroiclabs.com/docs/nakama/guides/concepts/social-sign-in/llm.md

This method attempts to load a device ID from secure storage, migrates legacy IDs from PlayerPrefs, or generates a new GUID if none exists. It ensures the ID is saved back to secure storage and PlayerPrefs for future access.

```csharp
private const string DeviceIdKey = "nakama.deviceId";

public string GetOrCreateDeviceId()
{
    // 1. Durable store first: iOS Keychain / Android Block Store.
    // SecureStore here stands in for your keychain or Block Store wrapper.
    var deviceId = SecureStore.Load(DeviceIdKey);

    // 2. Migrate an ID that older builds kept in PlayerPrefs.
    if (string.IsNullOrEmpty(deviceId))
    {
        deviceId = PlayerPrefs.GetString(DeviceIdKey);
    }

    // 3. First run: generate. A GUID meets Nakama's 10-128 byte requirement.
    if (string.IsNullOrEmpty(deviceId))
    {
        deviceId = Guid.NewGuid().ToString();
    }

    SecureStore.Save(DeviceIdKey, deviceId);
    PlayerPrefs.SetString(DeviceIdKey, deviceId);
    return deviceId;
}
```

--------------------------------

### Create Nakama Client

Source: https://heroiclabs.com/docs/nakama/client-libraries/defold/llm.md

Initialize the Nakama client with server connection details.

```lua
local defold = require "nakama.engine.defold"

local config = {
  host = 127.0.0.1,
  port = 7350,
  use_ssl = false,
  username = "defaultkey",
  engine = defold
}

local client = nakama.create_client(config)
```

--------------------------------

### Example main.go file

Source: https://heroiclabs.com/docs/nakama/guides/server-framework/debugging-with-delve/index.html

A sample Go runtime module that registers an RPC function named RpcTest for debugging purposes.

```go
package main

import (
	"context"
	"database/sql"
	"fmt"

	"github.com/heroiclabs/nakama-common/runtime"
)
func InitModule(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, initializer runtime.Initializer) error {
	logger.Debug("GO SERVER RUNTIME CODE LOADED")
	initializer.RegisterRpc("RpcTest", RpcTest)
	return nil
}

func RpcTest(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, payload string) (string, error) {
	logger.Debug("RpcTest RPC called")

    payloadExists := false
    
    if payload != "" {
        payloadExists = true
    }

    return fmt.Sprintf("{ \"payloadExists\": %v }", payloadExists), nil
}
```

--------------------------------

### Registering and Processing Server Events in Go

Source: https://heroiclabs.com/docs/nakama/concepts/events

This example shows how to implement event handlers for account updates and session lifecycle events, and how to register them in the InitModule function.

```go
package main

import (
    "context"
    "database/sql"
    "github.com/heroiclabs/nakama-common/api"
    "github.com/heroiclabs/nakama-common/runtime"
)

func afterUpdateAccount(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.UpdateAccountRequest) error {
    evt := &api.Event{
        Name:       "account_updated",
        Properties: map[string]string{},
        External:   false,
    }
    return nk.Event(context.Background(), evt)
}

func processEvent(ctx context.Context, logger runtime.Logger, evt *api.Event) {
    switch evt.GetName() {
    case "account_updated":
        logger.Debug("process evt: %+v", evt)
        // Send event to an analytics service.
    default:
        logger.Error("unrecognised evt: %+v", evt)
    }
}

func eventSessionEnd(ctx context.Context, logger runtime.Logger, evt *api.Event) {
   logger.Debug("process event session end: %+v", evt)
}

func eventSessionStart(ctx context.Context, logger runtime.Logger, evt *api.Event) {
    logger.Debug("process event session start: %+v", evt)
}

//noinspection GoUnusedExportedFunction
func InitModule(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, initializer runtime.Initializer) error {
    if err := initializer.RegisterAfterUpdateAccount(afterUpdateAccount); err != nil {
       return err
    }
    if err := initializer.RegisterEvent(processEvent); err != nil {
        return err
    }
    if err := initializer.RegisterEventSessionEnd(eventSessionEnd); err != nil {
       return err
    }
    if err := initializer.RegisterEventSessionStart(eventSessionStart); err != nil {
       return err
    }
    logger.Info("Server loaded.")
    return nil
}
```

--------------------------------

### GET /v2/matchmaker/stats

Source: https://heroiclabs.com/docs/nakama/api/client

Get matchmaker stats.

```APIDOC
## GET /v2/matchmaker/stats

### Description
Get matchmaker stats.

### Method
GET

### Endpoint
/v2/matchmaker/stats
```

--------------------------------

### Correct Static Data Caching

Source: https://heroiclabs.com/docs/nakama/server-framework/introduction/best-practices

This example demonstrates loading static data once at module initialization into a package-level structure for efficient access.

```go
var itemDefs map[string]ItemDef // loaded once, read-only afterwards

func InitModule(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, initializer runtime.Initializer) error {
	data, err := os.ReadFile("data/item_definitions.json")
	if err != nil {
		return err // fail fast at startup, not per request
	}
	if err := json.Unmarshal(data, &itemDefs); err != nil {
		return err
	}
	// ...
}

func RpcGetItemInfo(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, payload string) (string, error) {
	item, ok := itemDefs[payload]
	// ...
}
```

--------------------------------

### GET /v2/iap/subscription/{productId}

Source: https://heroiclabs.com/docs/nakama/api/client

Get subscription by product id.

```APIDOC
## GET /v2/iap/subscription/{productId}

### Description
Get subscription by product id.

### Method
GET

### Endpoint
/v2/iap/subscription/{productId}

### Parameters
#### Path Parameters
- **productId** (string) - Required - The ID of the product.
```

--------------------------------

### Encoded JWT Example

Source: https://heroiclabs.com/docs/nakama/concepts/session/management/index.html

An example of a cryptographically-signed JWT in its encoded string format.

```text
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJmNDA4MmFhMC1hYWQwLTQ1MjYtODkwZC1iYTUwYjI0NmJlMTkiLCJ1c24iOiJhS25pWU5pZ1FiIiwiZXhwIjoxNTk3NjY3MjIwfQ.1fdAmq3nrDcPy0k6BwPCcULmhLiB54Z_feEuDaINNsA
```

--------------------------------

### Invoke InitializeGameLift in Start

Source: https://heroiclabs.com/docs/nakama/guides/concepts/gamelift-integration/index.html

Call the initialization method from the Unity Start lifecycle method.

```csharp
private void Start()
{
  InitializeGameLift();
}
```

--------------------------------

### Create a Nakama Client

Source: https://heroiclabs.com/docs/nakama/client-libraries/cpp/index.html

Initialize the client by providing server connection parameters. It is recommended to maintain one client per server per game.

```cpp
NClientParameters params;
params.serverKey = "defaultkey";
params.host = "127.0.0.1";
params.port = DEFAULT_PORT;
auto client = createDefaultClient(params);
```

--------------------------------

### Leaderboard Record Metadata Example

Source: https://heroiclabs.com/docs/nakama/concepts/leaderboards/index.html

Example JSON structure for leaderboard record metadata.

```json
{
  "surface": "wet",
  "timeOfDay": "night",
  "car": "Porsche 918 Spyder"
}
```

--------------------------------

### Install latest nakama-runtime version

Source: https://heroiclabs.com/docs/nakama/server-framework/typescript-runtime/index.html

Command to install a specific version of the nakama-common package.

```bash
npm i https://github.com/heroiclabs/nakama-common#<version>
```

--------------------------------

### Initialize Nakama Client

Source: https://heroiclabs.com/docs/nakama/client-libraries/swift/llm.md

Create a Nakama client instance to connect to your server. It's recommended to have one client per server per game.

```swift
let client = GrpcClient(
    serverKey: "defaultkey",
    host: "127.0.0.1",
    ssl: false
)
```

--------------------------------

### Install Jest dependencies

Source: https://heroiclabs.com/docs/nakama/guides/server-framework/typescript-testing/index.html

Install the required packages for testing TypeScript with Jest and ts-auto-mock.

```bash
npm i -D jest @jest/globals ts-jest ts-auto-mock jest-ts-auto-mock ts-patch
```

--------------------------------

### Initialize Nakama Client

Source: https://heroiclabs.com/docs/nakama/client-libraries/javascript/llm.md

Create a Nakama Client instance to connect to your server. It's recommended to have one client per server per game.

```javascript
var client = new nakamajs.Client("defaultkey", "127.0.0.1", 7350);
```

--------------------------------

### Basic Hello World Module Initialization

Source: https://heroiclabs.com/docs/nakama/server-framework/typescript-runtime/llm.md

A simple 'Hello World' example for Nakama server runtime. This code must be placed in 'src/main.ts' and registered via the 'InitModule' function.

```typescript
let InitModule: nkruntime.InitModule =
        function(ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, initializer: nkruntime.Initializer) {
    logger.info("Hello World!");
}
```

--------------------------------

### Start Nakama Service

Source: https://heroiclabs.com/docs/nakama/getting-started/upgrade/index.html

Command to start the Nakama service on a Linux system using systemd.

```bash
sudo systemctl start nakama
```

--------------------------------

### Initialize and Create Match

Source: https://heroiclabs.com/docs/nakama/tutorials/godot/fishgame/index.html

Sets up the Nakama socket and multiplayer bridge, then initiates the creation of a new match.

```gdscript
func create_match(_nakama_socket: NakamaSocket) -> void:
	leave()
	_set_nakama_socket(_nakama_socket)
	match_mode = MatchMode.CREATE
	nakama_multiplayer_bridge.create_match()
```

--------------------------------

### Start local cluster

Source: https://heroiclabs.com/docs/nakama/guides/concepts/edgegap-integration/index.html

Command to build and start the local Nakama cluster using Docker Compose.

```bash
docker compose up --build -d
```

--------------------------------

### Install Rollup dependencies

Source: https://heroiclabs.com/docs/nakama/server-framework/typescript-runtime/index.html

Run this command to install Babel, Rollup, and their associated plugins as development dependencies.

```bash
npm i -D @babel/core @babel/plugin-external-helpers @babel/preset-env @rollup/plugin-babel @rollup/plugin-commonjs @rollup/plugin-json @rollup/plugin-node-resolve @rollup/plugin-typescript rollup tslib
```

--------------------------------

### Display All Nakama Configuration Flags

Source: https://heroiclabs.com/docs/nakama/getting-started/commands/llm.md

Use the `--help` command to display all available configuration flags for the Nakama server.

```sh
nakama --help
```

--------------------------------

### Install Project Dependencies Locally

Source: https://heroiclabs.com/docs/nakama/server-framework/typescript-runtime/llm.md

Installs all project dependencies, including development dependencies, using npm.

```bash
npm i
```

--------------------------------

### Start Nakama and Postgres Containers

Source: https://heroiclabs.com/docs/nakama/guides/server-framework/debugging-with-delve/llm.md

This command launches the Nakama and Postgres services defined in your docker-compose.yml file.

```bash
docker compose up

```

--------------------------------

### Registering Before Hooks in Go

Source: https://heroiclabs.com/docs/nakama/guides/server-framework/guarding-apis/llm.md

Examples of registering various 'Before' hooks in Go to intercept account, purchase, and storage operations.

```go
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeUnlinkFacebookInstantGame(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.AccountFacebookInstantGame) (*api.AccountFacebookInstantGame, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeUnlinkGameCenter(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.AccountGameCenter) (*api.AccountGameCenter, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeUnlinkGoogle(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.AccountGoogle) (*api.AccountGoogle, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeUnlinkSteam(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.AccountSteam) (*api.AccountSteam, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeUpdateAccount(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.UpdateAccountRequest) (*api.UpdateAccountRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeUpdateGroup(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.UpdateGroupRequest) (*api.UpdateGroupRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeValidatePurchaseApple(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.ValidatePurchaseAppleRequest) (*api.ValidatePurchaseAppleRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeValidatePurchaseFacebookInstant(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.ValidatePurchaseFacebookInstantRequest) (*api.ValidatePurchaseFacebookInstantRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeValidatePurchaseGoogle(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.ValidatePurchaseGoogleRequest) (*api.ValidatePurchaseGoogleRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeValidatePurchaseHuawei(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.ValidatePurchaseHuaweiRequest) (*api.ValidatePurchaseHuaweiRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeValidateSubscriptionApple(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.ValidateSubscriptionAppleRequest) (*api.ValidateSubscriptionAppleRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeValidateSubscriptionGoogle(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.ValidateSubscriptionGoogleRequest) (*api.ValidateSubscriptionGoogleRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeWriteLeaderboardRecord(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.WriteLeaderboardRecordRequest) (*api.WriteLeaderboardRecordRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeWriteStorageObjects(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.WriteStorageObjectsRequest) (*api.WriteStorageObjectsRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeWriteTournamentRecord(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.WriteTournamentRecordRequest) (*api.WriteTournamentRecordRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}

	return nil
}
```

--------------------------------

### Install Rollup and Babel Dependencies

Source: https://heroiclabs.com/docs/nakama/server-framework/typescript-runtime/llm.md

Installs the necessary development dependencies for Rollup, Babel, and TypeScript compilation.

```bash
npm i -D @babel/core @babel/plugin-external-helpers @babel/preset-env @rollup/plugin-babel @rollup/plugin-commonjs @rollup/plugin-json @rollup/plugin-node-resolve @rollup/plugin-typescript rollup tslib
```

--------------------------------

### Create a Nakama Client

Source: https://heroiclabs.com/docs/nakama/client-libraries/godot/index.html

Initialize the Nakama client with server connection details.

```gdscript
extends Node

var client : NakamaClient

func _ready():
    client = Nakama.create_client("defaultkey", "127.0.0.1", 7350, "http")
```

--------------------------------

### Install Nakama Runtime Types

Source: https://heroiclabs.com/docs/nakama/server-framework/typescript-runtime/llm.md

Installs the Nakama runtime types as a project dependency using NPM.

```shell
npm i 'https://github.com/heroiclabs/nakama-common'
```

--------------------------------

### Initialize Nakama Client

Source: https://heroiclabs.com/docs/nakama/client-libraries/cocos2d-js

Create a new client instance using default connection settings or custom parameters.

```javascript
// Default connection settings for a local Nakama server
var serverkey = "defaultkey";
var host = "127.0.0.1";
var port = "7350";
var useSSL = false;
var timeout = 7000; // ms

var client = new nakamajs.Client(serverkey, host, port, useSSL, timeout);

var client = new nakamajs.Client();
```

--------------------------------

### List Matches with Nakama Client

Source: https://heroiclabs.com/docs/nakama/client-libraries/unreal/index.html

Demonstrates how to list matches using the Nakama client, including setting up success and error delegates to handle the response.

```cpp
int32 MinPlayers = 2;
int32 MaxPlayers = 10;
int32 Limit = 10;
bool Authoritative = true;
FString Label = TEXT("");

FOnMatchlist ListMatchesSuccessDelegate;
ListMatchesSuccessDelegate.AddDynamic(this, &ASagiShiActor::OnListMatchesSuccess);

FOnError ListMatchesErrorDelegate;
ListMatchesErrorDelegate.AddDynamic(this, &ASagiShiActor::OnListMatchesError);

Client->ListMatches(Session, MinPlayers, MaxPlayers, Limit, Label, Authoritative, ListMatchesSuccessDelegate, ListMatchesErrorDelegate);

/* Delegate handlers */

void ASagiShiActor::OnListMatchesSuccess(const FNakamaMatchList& MatchList)
{
	for (int16 i = 0; i < MatchList.Matches.Num(); i++)
	{
		FNakamaMatch Match = MatchList.Matches[i];
		UE_LOG(LogTemp, Log, TEXT("%s:%d/10 players"), *Match.MatchId, Match.Size);
	}
}

void ASagiShiActor::OnListMatchesError(const FNakamaError& Error)
{
	UE_LOG(LogTemp, Error, TEXT("Error listing matches: %s"), *Error.Message);
}
```

--------------------------------

### List leaderboard records via REST API (GET)

Source: https://heroiclabs.com/docs/nakama/concepts/leaderboards/index.html

Lists records from a leaderboard using a GET request.

```http
GET /v2/leaderboard/<leaderboardId>
Host: 127.0.0.1:7350
Accept: application/json
Content-Type: application/json
Authorization: Bearer <session token>
```

--------------------------------

### Registering Before Hooks in Go

Source: https://heroiclabs.com/docs/nakama/guides/server-framework/guarding-apis

This example demonstrates how to register various 'Before' hooks using the initializer to intercept API requests such as authentication, group management, and storage operations.

```go
if err := initializer.RegisterBeforeAuthenticateCustom(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.AuthenticateCustomRequest) (*api.AuthenticateCustomRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeAuthenticateDevice(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.AuthenticateDeviceRequest) (*api.AuthenticateDeviceRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeAuthenticateEmail(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.AuthenticateEmailRequest) (*api.AuthenticateEmailRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeAuthenticateFacebook(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.AuthenticateFacebookRequest) (*api.AuthenticateFacebookRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeAuthenticateFacebookInstantGame(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.AuthenticateFacebookInstantGameRequest) (*api.AuthenticateFacebookInstantGameRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeAuthenticateGameCenter(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.AuthenticateGameCenterRequest) (*api.AuthenticateGameCenterRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeAuthenticateGoogle(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.AuthenticateGoogleRequest) (*api.AuthenticateGoogleRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeAuthenticateSteam(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.AuthenticateSteamRequest) (*api.AuthenticateSteamRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeBanGroupUsers(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.BanGroupUsersRequest) (*api.BanGroupUsersRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeBlockFriends(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.BlockFriendsRequest) (*api.BlockFriendsRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeCreateGroup(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.CreateGroupRequest) (*api.CreateGroupRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	//if err := initializer.RegisterBeforeDeleteAccount(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule) error {
	//	return nil
	//}); err != nil {
	//	return err
	//}
	if err := initializer.RegisterBeforeDeleteFriends(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.DeleteFriendsRequest) (*api.DeleteFriendsRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeDeleteGroup(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.DeleteGroupRequest) (*api.DeleteGroupRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeDeleteLeaderboardRecord(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.DeleteLeaderboardRecordRequest) (*api.DeleteLeaderboardRecordRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeDeleteNotifications(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.DeleteNotificationsRequest) (*api.DeleteNotificationsRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeDeleteStorageObjects(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.DeleteStorageObjectsRequest) (*api.DeleteStorageObjectsRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
	if err := initializer.RegisterBeforeDeleteTournamentRecord(func(ctx context.Context, logger runtime.Logger, db *sql.DB, nk runtime.NakamaModule, in *api.DeleteTournamentRecordRequest) (*api.DeleteTournamentRecordRequest, error) {
		return nil, nil
	}); err != nil {
		return err
	}
```

--------------------------------

### SubscriptionValidateGoogle Example

Source: https://heroiclabs.com/docs/nakama/server-framework/go-runtime/function-reference

Validates a Google Play Store receipt, with an optional example of overriding service account credentials.

```go
userId := "4c2ae592-b2a7-445e-98ec-697694478b1c"
receipt := "{\"json\":{\"orderId \":\"..\",\"packageName \":\"..\",\"productId \":\"..\",\"purchaseTime\":1607721533824,\"purchaseState\":0,\"purchaseToken\":\"..\",\"acknowledged\":false},\"signature \":\"..\",\"skuDetails \":{\"productId\":\"..\",\"type\":\"inapp\",\"price\":\"u20ac82.67\",\"price_amount_micros\":82672732,\"price_currency_code\":\"EUR\",\"title\":\"..\",\"description\":\"..\",\"skuDetailsToken\":\"..\"}}"
persist := true
validation, err := nk.SubscriptionValidateGoogle(ctx, userId, receipt, persist)
if err != nil {
	// Handle error
}
logger.Info("Validated subscription: %+v", validation.ValidatedSubscription)

// Override the configured service account credentials
validation, err = nk.SubscriptionValidateGoogle(ctx, userId, receipt, persist, struct {
	ClientEmail string
	PrivateKey  string
}{
	ClientEmail: "service-account@your-project.iam.gserviceaccount.com",
	PrivateKey:  "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
})
if err != nil {
	// Handle error
}
```

--------------------------------

### Install Project Dependencies

Source: https://heroiclabs.com/docs/nakama/tutorials/javascript/xoxo/index.html

Installs the necessary Node.js dependencies for the project using npm. Run this command in your terminal.

```bash
npm install
```

--------------------------------

### Step through execution with next

Source: https://heroiclabs.com/docs/nakama/guides/server-framework/debugging-with-delve/index.html

Use the next command to step into the executing function and observe the logger output.

```text
(dlv) next
2022-06-30T13:18:38Z debug layer=debugger nexting
{"level":"debug","ts":"2022-06-30T13:18:38.878Z","caller":"nakama-server-sandbox/main.go:17","msg":"RpcTest RPC called","runtime":"go","rpc_id":"RpcTest"}
> heroiclabs.com/nakama-server-sandbox.RpcTest() heroiclabs.com.-server-sandbox/main.go:19 (PC: 0x7f819f58d830)
```

--------------------------------

### Define Ready and Game Starting Op Codes (Lua)

Source: https://heroiclabs.com/docs/nakama/guides/concepts/lobby/index.html

Constants for identifying ready and game starting messages in Lua.

```lua
local READY_OP_CODE = 1
local GAME_STARTING_OP_CODE = 2
```

--------------------------------

### Creating Project Workspace

Source: https://heroiclabs.com/docs/nakama/server-framework/typescript-runtime/index.html

Initialize the project directory structure for source and build files.

```bash
mkdir -p ts-project/{src,build}
cd ts-project
```

--------------------------------

### Correct Batch Database Access Pattern

Source: https://heroiclabs.com/docs/nakama/server-framework/introduction/best-practices

This example shows the optimized approach using a single batched StorageRead call and re-indexing the results by user ID.

```go
func rpcLoadClanRoster(ctx context.Context, nk runtime.NakamaModule, memberIDs []string) (map[string]*api.StorageObject, error) {
	reads := make([]*runtime.StorageRead, 0, len(memberIDs))
	for _, userID := range memberIDs {
		reads = append(reads, &runtime.StorageRead{
			Collection: "progression",
			Key:        "season_state",
			UserID:     userID,
		})
	}

	// BATCHED: one call for the whole roster, regardless of size.
	objs, err := nk.StorageRead(ctx, reads)
	if err != nil {
		return nil, err
	}

	// Re-index by owner. Batch responses are NOT order-guaranteed and omit
	// missing keys entirely, so never assume objs[i] pairs with memberIDs[i].
	stateByUser := make(map[string]*api.StorageObject, len(objs))
	for _, o := range objs {
		stateByUser[o.UserId] = o
	}
	return stateByUser, nil // any roster size -> 1 round trip
}
```

--------------------------------

### Define Ready and Game Starting Op Codes (TypeScript)

Source: https://heroiclabs.com/docs/nakama/guides/concepts/lobby/index.html

Constants for identifying ready and game starting messages in TypeScript.

```typescript
const ReadyOpCode = 1
const GameStartingOpCode = 2
```

--------------------------------

### Create a Real-time Socket Client

Source: https://heroiclabs.com/docs/nakama/client-libraries/cpp/index.html

Initializes a real-time client from the main Nakama client instance and connects it using an existing session.

```cpp
NRtClientPtr rtClient;
rtClient = client->createRtClient();

bool createStatus = true;
rtClient->connect(session, createStatus);
```

--------------------------------

### Define Ready and Game Starting Op Codes (JavaScript)

Source: https://heroiclabs.com/docs/nakama/guides/concepts/lobby/index.html

Constants for identifying ready and game starting messages in JavaScript.

```javascript
const READY_OP_CODE = 1;
const GAME_STARTING_OP_CODE = 2;
```
Tokens:
Raw