Migrate to the Multiplayer Services SDK

Transfer from the individual services' SDKs to the unified Multiplayer Services SDK.

The Multiplayer Services SDK unites the functionality of the standalone SDKs from the following services:

If you're already using any of the SDKs from these individual services in your project but want to move to the unified Multiplayer Services SDK, you must first migrate from the individual services' packages to the Multiplayer Services package.

Migrate from Lobby

To migrate from the Lobby SDK to the unified Multiplayer Services SDK, do the following:

  1. Remove the Lobby package from the Package Manager.
  2. Install the Multiplayer Services package from the Package Manager.
  3. Change any usage of Lobbies.Instance to LobbyService.Instance

Note: If you use assembly definition files (Unity Manual), change any Lobby package reference to the Multiplayer Services package.

You have now migrated the functionality of the Lobby SDK to the Multiplayer Services SDK in your project.

Migrate from Matchmaker

To migrate from the Matchmaker SDK to the unified Multiplayer Services SDK, do the following:

  1. Remove the Matchmaker package from the Package Manager.
  2. Install the Multiplayer Services package from the Package Manager.

Note: If you use assembly definition files (Unity Manual), change any Matchmaker package reference to the Multiplayer Services package.

You have now migrated the functionality of the Matchmaker SDK to the Multiplayer Services SDK in your project.

Migrate from Multiplay

Before you begin, you need to split your code between client-side, server-side, and shared code using one of the following methods:

  • Use the UNITY_SERVER define symbol and encapsulate parts of your code in conditional compilation (marked by #if/#endif). Refer to Conditional compilation in Unity (Unity documentation) for more details.
  • Split the code into multiple assemblies using assembly definition files (Unity Manual), and only assign the Linux Dedicated Server platform to the server-side assembly definition.

Note: The Multiplay namespace within the Multiplayer Services package is available only on the server (marked by the UNITY_SERVER define symbol).

To migrate from the Multiplay SDK to the unified Multiplayer Services SDK, do the following:

  1. Remove the Multiplay package from the Package Manager.
  2. Install the Multiplayer Services package from the Package Manager.
  3. Update any assembly definition file referencing the Multiplay package to reference the Multiplayer Services package.

You have now migrated the functionality of the Multiplay SDK to the Multiplayer Services SDK in your project.

Migrate from Relay

To migrate from the Relay SDK to the unified Multiplayer Services SDK, do the following:

  1. Remove the Relay package from the Package Manager.
  2. Install the Multiplayer Services package from the Package Manager.
  3. Change any usage of Relay.Instance to RelayService.Instance.
  4. Change RelayServerData(hostAllocation, connectionType) constructors into AllocationUtils.ToRelayServerData(hostAllocation, connectionType). Refer to the code below for more details.

Note: If you use assembly definition files (Unity Manual), change any Relay package reference to the Multiplayer Services package.

If you use Relay with the Unity Transport Protocol (UTP), adapt the creation of the RelayServerData using the following sample code:

For the host

// maxConnections is the maximum number of connections the allocation is expecting
    // connectionType is the host connection type, this can be "dtls", "udp" or "wss"
    var allocation = await RelayService.Instance.CreateAllocationAsync(maxConnections);
    NetworkManager.Singleton.GetComponent<UnityTransport>().SetRelayServerData(AllocationUtils.ToRelayServerData(allocation, connectionType));

For the joining player

// connectionType is the host connection type, this can be "dtls", "udp" or "wss"
   // joinCode is the allocation join code shared by the host player after creating the allocation and retrieving the join code
    var allocation = await RelayService.Instance.JoinAllocationAsync(joinCode);
    NetworkManager.Singleton.GetComponent<UnityTransport>().SetRelayServerData(new RelayServerData(allocation, connectionType));

Refer to Use Relay with Netcode for GameObjects for more details on using Relay with Netcode for GameObjects with the Multiplayer Services SDK.