A drop-in lobby and matchmaking front-end for PurrNet.
PurrLobby gives you the multiplayer menu flow most games need: create a lobby, share a code, browse open lobbies when the selected backend supports it, chat, ready up, matchmake, and move everyone into a game scene together. The UI is already built. You choose a backend, assign your game scene, and customize the prefabs as needed.
Full documentation lives at purrnet.dev/docs. This README is a quick overview; the docs cover setup, providers, and customization in depth.
- Unity
2022.3or newer. - PurrNet and PurrUI.
- PurrServices when using the PurrNet Services lobby provider or Edgegap game allocator.
- Optional provider packages:
- Steamworks.NET for Steam providers.
- Nakama Unity for Nakama providers.
- Edgegap Unity plugin for Edgegap workflows.
Provider code is compiled out when its SDK is absent, so you only need the packages for the backends you actually use.
Install through the PurrNet package manager: open Tools > PurrNet > PurrNet
Packages (Ctrl+Shift+Alt+P), find PurrLobby in the list, and install.
PurrUI is listed as a dependency and is installed alongside it. The version
dropdown lets you pick a release or dev build.
The package page is at purrnet.dev/packages/purrlobby.
For local development, clone the repository and open it with a supported Unity
version. The checked-in Packages/manifest.json points at the dependency
versions used by the sample project.
Updating replaces the contents of the package. Any edits you have made to the shipped prefabs, scenes, materials, or scripts are overwritten.
Two ways to keep your customizations:
- Deselect your files during import. PurrLobby imports into
Assets/PurrLobby, so updating opens Unity's interactive import window. Uncheck anything you have modified to keep your version and take the rest of the update. - Duplicate before you edit. Copy any prefab or asset you plan to change
into your own folder outside
Assets/PurrLobbyand point your scenes at the copy. Updates then never touch your version.
The second approach is worth doing up front if you expect to restyle the UI heavily, since it keeps your work fully separate from the package.
- Menu flow: main menu, create lobby, join by code, lobby browser, matchmaking, and an in-lobby view with a player list and chat.
- Ready-up and owner-driven game start.
- A scene handoff that loads the game scene, connects the network transport, and returns to the menu on leave, game over, or connection loss.
- Swappable provider interfaces for sessions, lobbies, matchmaking, and game allocation.
- Prefabs and sample scenes under
Assets/PurrLobby.
| Provider | Lobbies | Lobby Browser | Matchmaking | Game Allocation |
|---|---|---|---|---|
| PurrNet Services | yes | yes | via generic lobby matchmaker | PurrTransport |
| Steam | yes | yes | via generic lobby matchmaker | Steam sockets |
| Nakama | create/join by id or code | basic (ids only) | yes | Nakama relayed match |
| Edgegap | no | no | yes | managed server assignment |
Providers advertise optional lobby actions through LobbyCapabilities. The
menu hides unsupported buttons automatically, so a backend without lobby
browsing will not show the browser entry point.
About the Nakama row: those entries describe this provider, not Nakama.
Nakama is fully capable of everything in the table, including rich lobby
listings, private lobbies and random join, through a custom server module
written against its Go, Lua, or TypeScript runtime. It deliberately targets a
stock Nakama server so it works with no server-side setup and no extra
dependencies. The trade-off is that relayed matches expose no name, metadata,
or max size to the browser, every match is publicly listed, and query filters
are ignored. Add your own server RPC and extend QueryLobbies to lift any of
these limits. Matchmaking is unaffected: NakamaMatchmakingProvider runs
Nakama's real matchmaker with tickets and min/max party size, no server module
required, and is the supported path for dropping players into a game together.
Edgegap matchmaking forms the match and returns ready-to-use connection info in
one step. Pair EdgegapMatchmakingProvider with EdgegapGameAllocator so the
matchmaker and allocator agree on transport and port selection.
- Open
Assets/PurrLobby/Scenes/MenuScene.unityfor a working example. - Select the
LobbyManagerin the scene and assign aGameOrchestrator. Preset orchestrators live underAssets/PurrLobby/Providers/.../Preset. - Choose the session, lobby, matchmaking, and game allocator providers for your backend.
- Set the allocator's game scene to your gameplay scene.
- Make sure the gameplay scene has a
NetworkManager. The allocator starts the host or client and adds the transport after loading the scene.
Auto-start flags can stay on. PurrLobby suppresses them for the duration of its own scene load and restores them afterwards, so your game scene doubles as a direct-play testing environment without getting in the lobby's way.
To customize the UI, edit the prefabs under Assets/PurrLobby/Prefabs/Views
and the smaller elements under Assets/PurrLobby/Prefabs/Elements, after
reading Updating.
Full documentation, including scene setup, provider settings, UI customization and writing your own backend, is at purrnet.dev/docs.
Implement the provider base classes in Assets/PurrLobby/Runtime/Providers:
SessionProviderLobbyProviderMatchmakingProviderGameAllocatorProvider
Lobby objects should implement the contracts in
Assets/PurrLobby/Runtime/Contracts, especially ILobby, IPlayer,
IMetadata, and ILobbyChat. The PurrNet provider under
Assets/PurrLobby/Providers/PurrNet is the smallest complete example; Nakama
is a fuller reference for relayed-match lobby state.