Unity Workflow LibraryUWLAbout

Topic 6 · Networking

Unity Multiplayer Services: Sessions, Relay, Lobby, Matchmaker and hosting

How Sessions wire Relay, Lobby and Matchmaker into Netcode for GameObjects or Entities, when to skip them, and how to verify a real connection.

Markdown version

Unity Multiplayer Services is Unity's own connection layer. It is not a netcode framework: it gets players into the same game, and Netcode for GameObjects or Netcode for Entities then synchronises the game. Account, data and economy services (Authentication, Cloud Save, Cloud Code and the rest of UGS) are in Unity Gaming Services ops; this page covers only the multiplayer connection services.

Package: Multiplayer Services SDK, com.unity.services.multiplayer, latest tag 2.4.0 (8 Oct 2026) in the Unity package registry, read 15 Oct 2026. Package manual.

What the SDK replaces

Unity's docs state that the Multiplayer Services SDK "unifies Lobby, Matchmaker, and Relay under a single, cohesive API, replacing their individual SDKs", and that sessions are "not a standalone service but instead an abstraction layer" over them (Multiplayer Services SDK). The standalone Relay pages tell Unity 6.0 and later projects to use this SDK to access Relay (Relay allocations). Treat the separate com.unity.services.relay and com.unity.services.lobby packages as superseded for new work; the existing rule UGS-LOBBY-RELAY-NETCODE-WIRING on Unity Gaming Services ops records the compile conflict when both layouts are installed.

What each service does

Service What it does Documented limit
Sessions (SDK layer) Creates, finds and joins a group of players and starts the netcode connection for them. CreateSessionAsync, JoinSessionByCodeAsync and CreateOrJoinSessionAsync are the entry points (Create a session). MaxPlayers includes the host.
Relay Routes all traffic through a Unity-run public server, so players connect without port forwarding and without seeing each other's IP addresses (Relay servers). 150 players per session; all traffic goes through one region chosen by the host (Relay limitations).
Lobby Lets players find, list and join groups before the game starts, and carries the connection data the session needs. The session system creates the lobby and heartbeats it for the host (Relay servers). 150 players, the same maximum as Relay (Players).
Matchmaker Places players into matches by rules (teams, skill or custom data, latency) instead of a list players choose from. Up to 100 teams, 25 team rules and 25 match rules per configuration; 10 queues with 10 pools each; one ticket request per second per player (Matchmaker rate limits).
Distributed Authority A Unity-hosted alternative to Relay for Netcode for GameObjects in which clients own objects and no player is the server. Selected with WithDistributedAuthorityNetwork() (Network connection management). No separate figure found in the pages read.
Dedicated server hosting (Multiplay) Withdrawn. Unity's status page: "As of April 1st 2026 Multiplay Game Server Hosting by Unity has been deprecated. Customers can no longer scale new game servers or make new allocations" (Unity status notice, 31 Mar 2026). Do not plan new work on it. Host dedicated servers with a third-party provider.

When to use which, and when to use none

  • No services: local multiplayer, LAN play, or a game you only run on a dedicated server with a public address. Use a direct connection (WithDirectNetwork() or the transport directly). Unity's docs warn that with direct connections in a client-hosted game every player's IP address is visible to the host (Network connection management).
  • Relay only (through a session): friends play together over the internet with one player hosting, and players share a join code.
  • Relay with Lobby: players browse or filter open games, or wait in a group before the match starts.
  • Matchmaker: strangers must be paired by skill, region or rules, and players should not choose the match themselves.
  • Distributed Authority: a Netcode for GameObjects game where no single player should carry the host's load and the trust model allows client ownership.
  • Third-party hosting instead of Relay: competitive games where the server must be authoritative and no player may host. Size guidance is on Networking stacks by game size.

How it fits with Netcode for GameObjects and Netcode for Entities

  • Unity Transport is the wire. Both Unity netcode packages use Unity Transport (com.unity.transport, latest tag 2.7.4, 13 Jul 2026) as their transport, and Relay connections run through it over UDP, DTLS or secure WebSocket (Unity multiplayer overview, Network connection management).
  • The session starts the netcode. With WithRelayNetwork() on the SessionOptions, the session system creates the Relay allocation, writes the connection data to the lobby, configures the netcode with it and starts the host; there is no separate allocate call (Relay servers). Do not also call NetworkManager.StartHost or StartClient yourself.
  • Netcode for GameObjects: integrated out of the box. Keep exactly one NetworkManager with a Unity Transport component in the scene.
  • Netcode for Entities: integrated out of the box. From SDK 1.2 the default handler creates the client and server worlds if none exist; older versions need the worlds created first (Network connection management).
  • Another framework (Mirror, FishNet and others): implement INetworkHandler and attach it with WithNetworkHandler(); this replaces the built-in integration (Network connection management).
  • Starting later: from SDK 1.2 the host can create the session first and start the network when everyone is ready, through session.AsHost().Network (same page).

Rules

  • MPS-ONE-SDK — new projects use com.unity.services.multiplayer only, never the standalone Relay or Lobby packages beside it. Check: Packages/manifest.json has the Multiplayer Services package and no com.unity.services.relay or com.unity.services.lobby entry.
  • MPS-SESSION-OWNS-START — when a session starts the network, game code never starts the netcode a second time. Check: search the project for StartHost, StartClient and StartServer; each remaining call is on a path that does not use sessions.
  • MPS-NO-MULTIPLAY-PLAN — no new design depends on Unity's Multiplay hosting. Check: the network design names the dedicated server host, or states that the game uses Relay or Distributed Authority.
  • MPS-SERVICES-ARE-RECORDED — the network design records which of Sessions, Relay, Lobby, Matchmaker and Distributed Authority the game uses, or "none", next to the netcode choice. This extends UNITY-NETWORKING-IS-PROJECT-SELECTED on Choosing a netcode stack & Netcode for GameObjects.

Verification an agent runs

  1. Packages: read Packages/manifest.json; confirm one Multiplayer Services package and one netcode package, and record both versions.
  2. Project link: in Edit > Project Settings > Services, confirm the project is linked to a Unity Cloud project, and that the services used are enabled in the dashboard for the environment the build targets.
  3. Sign-in: the game initialises Unity Services and signs in before any session call. Look for the sign-in success in the log before the first CreateSessionAsync.
  4. Two real clients: run a host and a client as separate processes (a build plus the Editor, or Multiplayer Play Mode). The host logs the session id and join code; the client joins by that code and logs a network state change to connected (Relay servers shows the session.Network.StateChanged event).
  5. Replication, not just connection: move or change one networked object on the host and confirm the client sees it. A connected state alone does not prove the netcode started.
  6. Leave and rejoin: the client leaves with session.LeaveAsync() and joins again; the host's player count returns to the same number.
  7. Limits: the session's MaxPlayers is within the documented 150, and any Matchmaker configuration is within the limits in the table above.
  8. Report the versions, the session id, which steps passed, and anything not run (for example, no second machine).