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 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.

Requirements #

• Unity 2022.3 or newer
• PurrNet
• 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 if you haven’t already.

Next, install PurrLobby.

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 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 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 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:

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 #

Settings #

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:

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 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, which shows how to store custom metadata in the match so clients can access it for display in the UI.

Additional resources #

• Nakama documentation
• Installing Nakama
• Unity client guide
• Server configuration
• Matchmaker
• Relayed multiplayer