# How to integrate Nakama with PurrNet's PurrLobby

**URL:** https://heroiclabs.com/docs/nakama/guides/concepts/purrnet-integration/
**Summary:** This guide explains how to integrate Nakama's authentication and matchmaking system with PurrNet's Unity networking library.
**Keywords:** purrnet, unity, matchmaking, multiplayer, lobby, purrlobby, purrnet integration
**Categories:** nakama, purrnet-integration, concepts

---


 # How to integrate Nakama with PurrNet's PurrLobby

This guide will demonstrate how you can use Nakama for authentication and matchmaking in PurrLobby, while keeping PurrNet for in-game networking.

 ## What is PurrNet?

[PurrNet](https://purrnet.dev/) is a Unity multiplayer networking library, and PurrLobby is its lobby and matchmaking layer. PurrLobby is modular: pick a supported backend provider, such as Nakama, and authentication, lobby creation and joining, matchmaking, and the menu-to-game handoff all work out of the box.

{{< youtube "sDNF1NjTM1A" >}}

{{< note "outline" "" hide_icon>}}
This guide is adapted from the PurrNet documentation. Read the [original guide](https://purrnet.dev/docs/tools/purrlobby/nakama).
{{</ note>}}

## Requirements

- Unity **2022.3** or newer
- [PurrNet](https://github.com/PurrNet/PurrNet)
- [Nakama Unity](https://github.com/heroiclabs/nakama-unity) (can be installed directly through the PurrNet plugin)

## Install Nakama

There are two pieces to set up: the Nakama Unity SDK in your project, and a server for it to talk to.

### The Unity SDK

First, make sure to [install the PurrNet framework](https://purrnet.dev/docs/getting-started/installation-setup#adding-it-to-your-project) if you haven't already.

Next, [install PurrLobby](https://purrnet.dev/docs/tools/purrlobby#installing).

Then, for the Nakama integration:

1. Open **Tools** > **PurrNet** > **PurrNet Packages** (`Ctrl+Shift+Alt+P`).
2. Find **Nakama** in the list.
3. Select a version and hit **Install**.

There's also a shortcut: assign any Nakama provider to your orchestrator and an **Install Nakama Unity** button shows up right in the `LobbyManager` inspector. Both paths pull the official Nakama package through UPM, so nobody has to hand-type a git URL or hunt down a tag.

We'd recommend either of those routes over installing manually. The Nakama SDK is also distributed through the Unity Asset Store and as a `Nakama.unitypackage` directly. Both of those drop files into `Assets/` rather than installing a proper UPM package. Because PurrLobby's Nakama providers only activate when they detect the UPM package, those two routes leave the providers switched off.

The [Unity client guide](/docs/nakama/client-libraries/unity/) walks through every installation option, including the manual UPM git URL for anyone who wants to manage it by hand.

The adapter configuration described in that guide is already wired up for you in PurrLobby. It builds the Nakama client with `UnityWebRequestAdapter`, the WebGL-safe HTTP path. It opens the socket through `NewSocket`, which automatically selects `JsWebSocketAdapter` on WebGL builds and dispatches events back on Unity's main thread.

## Test the server locally

The Nakama server runs locally in Docker, which is the quickest way to develop against it. Follow the [Docker install guide](/docs/nakama/getting-started/install/docker/) to get your server up and running quickly.

Open <http://127.0.0.1:7351> for the console and sign in with `admin` / `password`. It's genuinely useful while you're building out a lobby flow: watch matches appear and disappear, inspect accounts created through device login, and tail server logs as players join.

### Connect PurrLobby to it

Preset assets ship in `Assets/PurrLobby/Providers/Nakama/Preset`, including a pre-filled orchestrator. Drag `Orchestrator.Nakama` onto your `LobbyManager`, and you're done. The shipped `Nakama Config` already points at a local server, so a fresh Docker instance needs no changes on the Unity side.

Press play and the menu authenticates against your container. Watch the [console](http://127.0.0.1:7351) to see the account show up.

The local defaults are development values, not production ones. Change the server key before exposing an instance beyond your own machine, and use HTTPS in production.

## Point at a server

The endpoint lives on a `NakamaConfig` asset (**Create** > **PurrLobby** > **Nakama** > **Config**), which `NakamaSessionProvider` references:

| Field | Default | Notes |
| ----- | ------- | ----- |
| `Scheme` | `Http` | Switch to `Https` for any remote server |
| `Host` | `127.0.0.1` | Hostname or IP |
| `Port` | `7350` | Client API port. Usually `443` over HTTPS |
| `Server Key` | `defaultkey` | Must match your server's configured key |

For Heroic Cloud or a self-hosted instance, set `Scheme` to `Https`, `Host` to the address shown in your Heroic Cloud dashboard, `Port` to `443`, and `Server Key` to whatever key that instance is configured with.

Keeping separate config assets for local and hosted setups, and simply swapping which one the session provider points to, is an easy way to move between environments without touching individual fields.

## What PurrLobby uses from Nakama

| Role | Asset | Backed by |
| ---- | ----- | --------- |
| Session | `NakamaSessionProvider` | Nakama device authentication |
| Lobby | `NakamaLobbyProvider` | Nakama relayed matches |
| Matchmaking | `NakamaMatchmakingProvider` | Nakama's ticket-based matchmaker |
| Game allocation | `NakamaGameAllocator` | Nakama relayed match as the transport |

### Settings

| Asset | Settings |
| ----- | -------- |
| `NakamaConfig` | `Scheme`, `Host`, `Port`, `Server Key` |
| `NakamaSessionProvider` | `Config`, `Session PlayerPref Key` |
| `NakamaLobbyProvider` | `Session Provider`, `Max Players`, `Snapshot Timeout Ms` (4000), `Query Limit` (100) |
| `NakamaMatchmakingProvider` | `Min Count` (2), `Max Count` (4) |
| `NakamaGameAllocator` | `Game Scene`, `Wait For Game Start Flag` (off) |

`Session PlayerPref Key` is where the device session token gets cached, so returning players skip the login step. `Snapshot Timeout Ms` sets how long a joining player waits for the lobby owner's first state snapshot before the join fails. `Query Limit` caps how many matches show up in the browser. `Wait For Game Start Flag` makes the host wait on a lobby metadata flag before connecting. Leave it off unless your flow specifically needs it, most teams preload the scene and connect right away.

## Choose a game allocator

`NakamaGameAllocator` isn't built for fast-paced games. It routes gameplay through Nakama's relayed match socket, which is a WebSocket carrying a custom message protocol. That's a solid fit for turn-based games, card and board games, and anything else where a bit of latency isn't a dealbreaker. It's the wrong choice for shooters, fighting games, racing, or anything needing tight, low-latency networking.

That's fine, though, because the orchestrator's four slots are independent of each other. Nakama is strong at session, lobby, and matchmaking, so keep it for those roles and swap out just the game allocator for something lower-latency:

| Instead of `NakamaGameAllocator` | Gameplay runs over |
| --------------------------------- | ------------------- |
| `PurrTransportGameAllocator` | PurrTransport relay |
| `SteamGameAllocator` | Steam relay sockets |
| A custom allocator | Whatever transport you configure, direct UDP, for example |

Running a Nakama session, Nakama lobbies, Nakama's matchmaker, and PurrTransport for the actual match is a perfectly normal combination. The menu flow doesn't change. Only the transport the game scene connects with does.

See PurrNet's [Custom providers](https://purrnet.dev/docs/tools/purrlobby/custom-providers) page if none of the shipped allocators fit your case.

## Capabilities and how to extend them

The provider advertises `CreateLobby`, `JoinLobbyById`, `JoinLobbyByCode`, and `QueryLobbies`.

These limits belong to the provider, not to Nakama itself. Nakama is fully capable of rich lobby listings, private lobbies, and random join. Doing so requires writing some custom server code in Go, Lua, or TypeScript. This particular provider deliberately targets a **stock Nakama server**, so it works out of the box with no server-side setup and no extra dependencies.

The trade-off: relayed matches expose no name, metadata, or max size to the browser, so listings show only the match ID, every match is publicly listed, and query filters get ignored.

To lift any of those limits, see the [Lobby System guide](/docs/nakama/guides/concepts/lobby), which shows how to store custom metadata in the match so clients can access it for display in the UI.

## Additional resources

- [Nakama documentation](/docs/nakama/)
- [Installing Nakama](/docs/nakama/getting-started/install/)
- [Unity client guide](/docs/nakama/client-libraries/unity/)
- [Server configuration](/docs/nakama/getting-started/configuration/)
- [Matchmaker](/docs/nakama/concepts/multiplayer/matchmaker/)
- [Relayed multiplayer](/docs/nakama/concepts/multiplayer/relayed/)