Multiplayer Services SDK

https://docs.unity.com/en-us/mps-sdk
Admin
Multiplayer Services SDK is Unity's unified platform for building multiplayer games with integrated...
Tokens:94,377
Snippets:961
Trust Score:10
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### StartHostWithRelay function

Source: https://docs.unity.com/en-us/mps-sdk/tutorials/relay-and-ngo

Creates a Relay allocation, requests a join code, and starts a host. Requires the maximum number of connections and the connection type (udp, dtls, or wss). Adapt the authentication and error handling as needed. Returns the join code if the host starts successfully, otherwise null.

```csharp
public async Task<string> StartHostWithRelay(int maxConnections, string connectionType)
{
    await UnityServices.InitializeAsync();
    if (!AuthenticationService.Instance.IsSignedIn)
    {
        await AuthenticationService.Instance.SignInAnonymouslyAsync();
    }
    var allocation = await RelayService.Instance.CreateAllocationAsync(maxConnections);
    NetworkManager.Singleton.GetComponent<UnityTransport>().SetRelayServerData(AllocationUtils.ToRelayServerData(allocation, connectionType));
    var joinCode = await RelayService.Instance.GetJoinCodeAsync(allocation.AllocationId);
    return NetworkManager.Singleton.StartHost() ? joinCode : null;
}
```

--------------------------------

### Create allocation request with QoS (C#)

Source: https://docs.unity.com/en-us/mps-sdk/networking/qos

Example of creating an allocation request without specifying a region, triggering the allocations service to use QoS data to select the best region. The code initializes Unity Services, authenticates anonymously if needed, creates an allocation, gets a join code, configures the transport with Relay server data, and starts the host. Note that on WebGL, QoS measurements use WebTransport instead of UDP and require a browser that supports WebTransport.

```csharp
private async Task<string> StartRelayServer()
{
    // Initialize UGS and authenticate if not already signed in
    await UnityServices.InitializeAsync();
    if (!AuthenticationService.Instance.IsSignedIn)
    {
        await AuthenticationService.Instance.SignInAnonymouslyAsync();
    }

    // Request an allocation to the Relay service
    var relayMaxPlayers = 5;
    Allocation allocation;
    try
    {
        allocation = await RelayService.Instance.CreateAllocationAsync(relayMaxPlayers);
    }
    catch (Exception e)
    {
        Debug.LogError($"Create allocation request failed: {e.Message}");
        return null;
    }

    // Request the join code to share with clients
    string joinCode;
    try
    {
        joinCode = await RelayService.Instance.GetJoinCodeAsync(allocation.AllocationId);
    }
    catch (Exception e)
    {
        Debug.LogError($"Create join code request failed: {e.Message}");
        return null;
    }

    // Configure the transport with Relay server data using AllocationUtils
    NetworkManager.Singleton.GetComponent<UnityTransport>()
        .SetRelayServerData(AllocationUtils.ToRelayServerData(allocation, "dtls"));

    // Start the host (or use StartServer() for a dedicated server)
    return NetworkManager.Singleton.StartHost() ? joinCode : null;
}
```

--------------------------------

### Delay network start with Session API (StartSessionAsHost and JoinSessionAsClient)

Source: https://docs.unity.com/en-us/mps-sdk/manage-session-network-connection

Shows how to delay starting the network connection until all players have joined. The host creates a session without calling With<X>Network(), then starts DirectNetworkAsync when the max player count is reached. The client joins by code and logs network state changes.

```csharp
async Task StartSessionAsHost()
{
    var options = new SessionOptions { MaxPlayers = 4 }; // note the omitted `With<X>Network() call.

    var session = await MultiplayerService.Instance.CreateSessionAsync(options);
    session.PlayerJoined += OnPlayerJoined;
    session.Network.StartFailed += OnNetworkStartFailed;
    session.Network.StateChanged += OnNetworkStateChanged;

    Debug.Log($"Session {session.Id} created! Join code: {session.Code}");

    void OnPlayerJoined(string playerId)
    {
        // verify if we have reached the max player count
        if (session.PlayerCount == session.MaxPlayers)
        {
            var networkOptions
                = new DirectNetworkOptions(ListenIPAddress.AnyIpv4, PublishIPAddress.LoopbackIpv4, 7777);

            // start the network once max player count have been reached
            _ = session.Network.StartDirectNetworkAsync(networkOptions);
        }
    }

    void OnNetworkStateChanged(NetworkState state)
    {
        switch (state)
        {
            case NetworkState.Starting:
                Debug.Log("Starting network...");
                break;
            case NetworkState.Started:
                Debug.Log($"Network has started, listening on: {session.Network.NetworkInfo.ListenAddress}, " +
                          $"and publishing on: {session.Network.NetworkInfo.PublishAddress} created!");
                break;
            default:
                Debug.Log($"[{nameof(StartSessionAsHost)}] Network state has changed! New State:{state:G}");
                break;
        }
    }

    void OnNetworkStartFailed(SessionError error)
    {
        // handle the error
        Debug.LogError($"Network start failed: {error:G}");
    }
}

async Task JoinSessionAsClient(string sessionJoinCode)
{
    // Join the session
    var session = await MultiplayerService.Instance.JoinSessionByCodeAsync(sessionJoinCode);

    Debug.Log($"Network state at the time of connection was: {session.Network.State:G}.");

    session.Network.StateChanged += OnNetworkStateChanged;

    void OnNetworkStateChanged(NetworkState state)
    {
        Debug.Log($"[{nameof(JoinSessionAsClient)}] Network state has changed! New State:{state:G}");
    }
}
```

--------------------------------

### Ticket Example for 60 Players

Source: https://docs.unity.com/en-us/mps-sdk/matchmaking/matchmaking-rule-samples

Shows a compatible ticket with one player without custom data.

```json
{
    "queueName": "Default",
    "attributes": {},
    "players": [{
            "id": "x7e9zb9t1928r0zw8x5j1sxhowkl",
            "customData": {}
        }
    ]
}
```

--------------------------------

### Ticket and Player Data with QoS Results

Source: https://docs.unity.com/en-us/mps-sdk/matchmaking/matchmaking-rule-samples

Example ticket and player data including QoS results with latency and packet loss for two regions.

```json
{
    "queueName": "Default",
    "attributes": {},
    "players": [{
            "id": "w4505uhp7ohr27di0ob9qdncaq5b",
            "customData": {},
            "qosResults":[
                {
                    "regionId": "61dd5b48-d24c-11ed-afa1-0242ac120002",
                    "packetLoss": 0.8,
                    "latency": 50
                },
                {
                    "regionId": "cf32c6e1-46ff-4904-9a37-359fc66bf382",
                    "packetLoss": 0.0,
                    "latency": 10
                }
            ]
        }
    ]
}
```

--------------------------------

### Ticket Example for 5v5 Red vs Blue

Source: https://docs.unity.com/en-us/mps-sdk/matchmaking/matchmaking-rule-samples

Shows a compatible ticket with one player who has custom data setting 'Team' to 'Blue'.

```json
{
    "queueName": "Default",
    "attributes": {},
    "players": [{
            "id": "e16naw0e6cgm8kw3vimtxt9qmhva",
            "customData": {
                "Team": "Blue"
            }
        }
    ]
}
```

--------------------------------

### Install required packages for A/B testing

Source: https://docs.unity.com/en-us/mps-sdk/matchmaking/ab-testing

Package names to install from the Unity Registry in the Package Manager for A/B testing support. The Multiplayer Services package includes the Unity Matchmaker Service API, and the Analytics package is required for A/B testing; without it, tickets are silently sent to the pool's primary variant.

```text
com.unity.services.multiplayer
```

```text
com.unity.services.analytics
```

--------------------------------

### Authenticate server with service account

Source: https://docs.unity.com/en-us/mps-sdk/game-server-hosting-support

Authenticate the game server with a service account before using Multiplayer Services. Refer to Create a service account for setup details.

```csharp
ServerAuthenticationService.Instance.SignInWithServiceAccountAsync
```

--------------------------------

### Create a matchmaking ticket with Unity SDK

Source: https://docs.unity.com/en-us/mps-sdk/matchmaking/get-started-mm

Unity C# example that initializes Unity Services, signs in anonymously, and calls MultiplayerService.Instance.MatchmakeSessionAsync with MatchmakerOptions and SessionOptions. Includes optional ticket attributes and player properties, and a CancelMatchmaking method that cancels the matchmaking token.

```csharp
using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using Unity.Services.Authentication;
using Unity.Services.Core;
using Unity.Services.Multiplayer;
using UnityEngine;

public class MatchmakerExample : MonoBehaviour
{
    ISession m_Session;
    CancellationTokenSource m_MatchmakingCts;

    async void Start()
    {
        await UnityServices.InitializeAsync();
        await AuthenticationService.Instance.SignInAnonymouslyAsync();

        await StartMatchmakingAsync();
    }

    async Task StartMatchmakingAsync()
    {
        m_MatchmakingCts = new CancellationTokenSource();

        var matchOptions = new MatchmakerOptions
        {
            QueueName = "MyQueue",
            // Optional: filters/attributes used by pool rules
            TicketAttributes = new Dictionary<string, object>
            {
                { "gameMode", "ranked" }
            },
            // Optional: per-player custom data used by matchmaking rules
            PlayerProperties = new Dictionary<string, PlayerProperty>
            {
                { "skill", new PlayerProperty("1200") }
            }
        };

        var sessionOptions = new SessionOptions
        {
            MaxPlayers = 5
        }.WithRelayNetwork(); // or .WithDistributedAuthorityNetwork() for Distributed Authority

        try
        {
            m_Session = await MultiplayerService.Instance.MatchmakeSessionAsync(
                matchOptions, sessionOptions, m_MatchmakingCts.Token);

            Debug.Log($"Match found and session joined: {m_Session.Id}");
        }
        catch (SessionException e)
        {
            Debug.LogError($"Matchmaking failed: {e.Message}");
        }
    }

    // Cancel matchmaking
    public void CancelMatchmaking()
    {
        m_MatchmakingCts?.Cancel();
    }
}
```

--------------------------------

### Manually start and stop backfilling

Source: https://docs.unity.com/en-us/mps-sdk/game-server-hosting-support

Manually start and stop the backfilling process for a session. Useful when players should not join, such as when the session is about to end or during a cinematic.

```csharp
IServerSession session = await MultiplayerServerService.Instance.CreateMatchSessionAsync(matchId, sessionOptions);

// Start the backfilling if it is not already in progress
await session.StartBackfillingAsync();

/// Stop the backfilling
await session.StopBackfillingAsync();
```

--------------------------------

### Allocate Relay and create session using WithRelayNetwork()

Source: https://docs.unity.com/en-us/mps-sdk/networking/relay-servers

Creates a session with a Relay allocation by calling WithRelayNetwork() on SessionOptions. Pass RelayNetworkOptions into WithRelayNetwork(...) to control protocol and region. Logs the session ID and join code.

```csharp
async Task<ISession> AllocateRelayAndCreateSession()
{
    var options = new SessionOptions { MaxPlayers = 4 }.WithRelayNetwork();
    var session = await MultiplayerService.Instance.CreateSessionAsync(options);
    Debug.Log($"Session {session.Id} created with a Relay allocation. Join code: {session.Code}");
    return session;
}
```

--------------------------------

### Example A/B test result JSON

Source: https://docs.unity.com/en-us/mps-sdk/matchmaking/ab-testing

Example JSON response from the A/B test result, showing fields isAbTesting, variantId, poolId, and basePoolId. This is the expected output when the ticket is correctly assigned to a variant.

```json
{
  "isAbTesting": true,
  "variantId": "aaaaaaaa-cdf2-4752-bae1-52ecc90d38c6:Variant 1",
  "poolId": "bbbbbbbb-722f-40f2-87f4-28ec307b7d0c",
  "basePoolId": "cccccccc-39a0-42ca-a15e-77544d7ffe41"
}
```

--------------------------------

### Explicit Network Startup APIs

Source: https://docs.unity.com/en-us/mps-sdk/session-networking

These are the API calls a host can use to explicitly start the network after session creation when no network type was configured up front. They correspond to the network types WithRelayNetwork, WithDirectNetwork, and WithDistributedAuthorityNetwork.

```csharp
StartRelayNetwork
```

```csharp
StartDirectNetwork
```

```csharp
StartDistributedAuthorityNetwork
```

--------------------------------

### Base relaxation contract example

Source: https://docs.unity.com/en-us/mps-sdk/matchmaking/rule-relaxations

Base relaxation contract example. The Relaxations array contains objects with Type, Value, AtSeconds, and AgeType fields. AtSeconds is the number of seconds (inclusive) after which the relaxation is triggered, and AgeType uses Oldest (default), Average, or Youngest ticket times.

```json
{
 ...
 Relaxations: [
   {
     "Type": "RelaxationType",
     "Value": 70,
     "AtSeconds": 5,
     "AgeType": "Oldest/Average/Youngest"
   }
 ]
}
```

--------------------------------

### Track session creation events with SessionObserver

Source: https://docs.unity.com/en-us/mps-sdk/session-observer

Use this example to track session creation events for a specific session type. It shows how to subscribe to the AddingSessionStarted, SessionAdded, and AddingSessionFailed events, and how to create a session with the WithRelayNetwork() option. The SessionObserver is used within an async using block to ensure proper disposal.

```csharp
void OnAddingSessionStarted(AddingSessionOptions addingSessionOptions) {
    Debug.Log($"A session of type {addingSessionOptions.Type} is being added.");
}

void OnSessionAdded(ISession session) {
    Debug.Log($"A session of type {session.Type} has been added.");
}

void OnAddingSessionFailed(AddingSessionOptions addingSessionOptions, SessionException exception) {
    Debug.Log($"The addition of a session of type {addingSessionOptions.Type} has failed with message {exception.Message}.");
}

// ...

async Task CreateSession() {
    async using (var sessionObserver = new SessionObserver("my-session-type")) {
        sessionObserver.AddingSessionStarted += OnAddingSessionStarted;
        sessionObserver.SessionAdded += OnSessionAdded;
        sessionObserver.AddingSessionFailed += OnAddingSessionFailed;

        var sessionOptions = new Sessionoptions(){
            Type = "my-session-type"
        }.WithRelayNetwork();
        await Multiplayer.Instance.CreateSessionAsync(sessionOptions);
    }
}
```

--------------------------------

### Average skill of players

Source: https://docs.unity.com/en-us/mps-sdk/matchmaking/mm-rules

Example of averaging the skill of all players in a match or team.

```json
{ ..."Source": "Players.CustomData.Skill.Avg"... }
```

--------------------------------

### Quick Join with MatchmakeSessionAsync

Source: https://docs.unity.com/en-us/mps-sdk/matchmake-lobby

C# example that finds and joins a session with at least 1 available slot and the property 'map 1'. It sets a 5-second timeout and optionally creates a new session if none is found. The session is configured with Relay networking.

```csharp
var quickJoinOptions = new QuickJoinOptions()
{
    Filters = new List<FilterOption>
    {
        new(FilterField.AvailableSlots, "1", FilterOperation.GreaterOrEqual),
        new (FilterField.StringIndex1, "map 1", FilterOperation.Equal)
    },
    Timeout = TimeSpan.FromSeconds(5),
    CreateSession = true
};

var sessionOptions = new SessionOptions()
{
    MaxPlayers = 2,
    Type = "Session",
}.WithRelayNetwork();

ISession session = await MultiplayerService.Instance.MatchmakeSessionAsync(quickJoinOptions, sessionOptions);
```

--------------------------------

### Access Skill field

Source: https://docs.unity.com/en-us/mps-sdk/matchmaking/mm-rules

Example of accessing the Skill field from player custom data.

```json
{ ..."Source": "Players.CustomData.Skill"... }
```

--------------------------------

### Find and join a session using Matchmaker

Source: https://docs.unity.com/en-us/mps-sdk/adv-matchmaking

Creates matchmaker and session options, then calls MatchmakeSessionAsync to find and join a session. Requires a queue named 'Friendly' and the default pool to be configured.

```csharp
var matchmakerOptions = new MatchmakerOptions
{
    QueueName = "Friendly"
};

var sessionOptions = new SessionOptions()
{
    MaxPlayers = 2
}.WithDirectNetwork();

var matchmakerCancellationSource = new CancellationTokenSource();

ISession session = await MultiplayerService.Instance.MatchmakeSessionAsync(matchmakerOptions, sessionOptions, matchmakerCancellationSource.Token);
```

--------------------------------

### EnableHostMigrationSystem.cs

Source: https://docs.unity.com/en-us/mps-sdk/build-with-netcode-for-entities

Creates the EnableHostMigrationSystem that enables host migration by adding the EnableHostMigration component and setting StoreOwnGhosts to true. The system disables itself after the first update and requires HostMigrationStats to exist.

```csharp
using Unity.Burst;
using Unity.Collections;
using Unity.Entities;
using Unity.NetCode;
using Unity.NetCode.HostMigration;

public struct GameHostMigrationCompleted : IComponentData { }

[BurstCompile]
[WorldSystemFilter(WorldSystemFilterFlags.ClientSimulation | WorldSystemFilterFlags.ServerSimulation |
    WorldSystemFilterFlags.ThinClientSimulation)]
public partial struct EnableHostMigrationSystem : ISystem
{
    public void OnCreate(ref SystemState state)
    {
        state.RequireForUpdate<HostMigrationStats>();

        //burst compatible way
        var entity = state.WorldUnmanaged.EntityManager.CreateEntity();
        state.WorldUnmanaged.EntityManager.AddComponent(entity, ComponentType.ReadOnly<EnableHostMigration>());
    }
     [BurstCompile]
     public void OnUpdate(ref SystemState state)
     {
         if(SystemAPI.TryGetSingletonRW<HostMigrationConfig>(out var config));
         {
             config.ValueRW.StoreOwnGhosts = true;
             // After first run, disable the system.
             state.Enabled = false;
         }
     }
}
```

--------------------------------

### 1v1 Ticket and Player Data

Source: https://docs.unity.com/en-us/mps-sdk/matchmaking/matchmaking-rule-samples

Example ticket and player data for a 1v1 match, with a single player and no custom data.

```json
{
    "queueName": "Default",
    "attributes": {},
    "players": [{
        "id": "swsqozxo6qxm9fmm38khh3tddv35",
        "customData": {}
    }]
}
```

--------------------------------

### Create session with client-hosted relay and overridden options

Source: https://docs.unity.com/en-us/mps-sdk/manage-session-network-connection

Creates a session as host with a client-hosted solution, overriding default relay options. The region parameter forces a specific Relay region and skips QoS auto-selection; if null, QoS determines the optimal region. The PreserveRegion flag (true) keeps the region during host migration.

```csharp
async Task StartSessionAsHost(string region = null)
{
    var options = new SessionOptions
    {
      MaxPlayers = 2
    }.WithRelayNetwork(new RelayNetworkOptions(RelayProtocol.Default, region, true)); // or WithDistributedAuthorityNetwork() to use Distributed Authority instead of Relay
    var session = await MultiplayerService.Instance.CreateSessionAsync(options);
    Debug.Log($"Session {session.Id} created! Join code: {session.Code}");
}
```

--------------------------------

### Configure session options with backfilling

Source: https://docs.unity.com/en-us/mps-sdk/game-server-hosting-support

Configure session options to enable automatic backfilling when a player leaves. Requires the "Matchmaker Backfill Admin" permission on the service account. MaxPlayers must be equal to or higher than the maximum players set in the matchmaking configuration.

```csharp
// Adapt session options to your game needs 
var sessionOptions = new SessionOptions()
{
  MaxPlayers = 2
};
// Add backfilling configuration if you want the session to automatically set up backfill when a player leaves.
// This requires having the "Matchmaker Backfill Admin" permission on your service account.
sessionOptions.WithBackfillingConfiguration(
    enable: true,
    automaticallyRemovePlayers: true,
    autoStart: true,
    playerConnectionTimeout: 30,
    backfillingLoopInterval: 1);
```

--------------------------------

### Replace relaxation with ReferenceControl.Replace

Source: https://docs.unity.com/en-us/mps-sdk/matchmaking/rule-relaxations

Use this relaxation to replace the reference value with another type once triggered. The example replaces the value with 300 at 10 seconds.

```json
{ 
   "Type": "ReferenceControl.Replace", 
   "Value": 300, 
   "AtSeconds": 10 
}
```

--------------------------------

### Create Session as Host with Relay or Distributed Authority

Source: https://docs.unity.com/en-us/mps-sdk/create-session

Use this snippet to create a session as the host. It sets MaxPlayers to 2, configures networking via WithRelayNetwork() or WithDistributedAuthorityNetwork(), and logs the session ID and join code. The session is created with CreateSessionAsync, making the player the host.

```csharp
async Task StartSessionAsHost()
{
    var options = new SessionOptions
    {
      MaxPlayers = 2
    }.WithRelayNetwork(); // or WithDistributedAuthorityNetwork() to use Distributed Authority instead of Relay
    var session = await MultiplayerService.Instance.CreateSessionAsync(options);
    Debug.Log($"Session {session.Id} created! Join code: {session.Code}");
}
```

--------------------------------

### Enable relaxation with RuleControl.Enable

Source: https://docs.unity.com/en-us/mps-sdk/matchmaking/rule-relaxations

Use this relaxation to apply the associated rule once triggered. The example sets the trigger at 5 seconds and targets the youngest player.

```json
{ 
   "Type": "RuleControl.Enable", 
   "AtSeconds": 5, 
   "AgeType": "Youngest" 
}
```

--------------------------------

### lobby is locked

Source: https://docs.unity.com/en-us/mps-sdk/lobby-error-messages

Example of a lower-level error code from components like Lobby, nested within the SessionException message rather than having its own explicit SessionError code.

```plaintext
lobby is locked
```

--------------------------------

### Host: Create allocation and set RelayServerData

Source: https://docs.unity.com/en-us/mps-sdk/migration-path

Sample code for the host when using Relay with Unity Transport Protocol (UTP) and the Multiplayer Services SDK. Creates an allocation, converts it to RelayServerData, and sets it on UnityTransport.

```csharp
// maxConnections is the maximum number of connections the allocation is expecting
// connectionType is the host connection type, this can be "dtls", "udp" or "wss"
// create allocation
var allocation = await RelayService.Instance.CreateAllocationAsync(maxConnections);

var relayServerData = allocation.ToRelayServerData(connectionType);

NetworkManager.Singleton.GetComponent<UnityTransport>().SetRelayServerData(relayServerData);
```

--------------------------------

### Join session and connect to configured network type

Source: https://docs.unity.com/en-us/mps-sdk/networking/relay-servers

Joins a session by join code and connects to the configured network type. Logs the session ID and network state, and subscribes to network state changes. Throws SessionException on failure, which is caught and logged.

```csharp
public async Task JoinSessionByCode(string joinCode)
{
    try
    {
        var session = await MultiplayerService.Instance.JoinSessionByCodeAsync(joinCode);
        Debug.Log($"Joined session {session.Id}. Network state: {session.Network.State:G}");
        session.Network.StateChanged += state => Debug.Log($"Network state changed: {state:G}");
    }
    catch (SessionException e)
    {
        Debug.LogError($"Failed to join session: {e.Error}");
    }
}
```

--------------------------------

### Match Rule: Leaderboard Tier Equality

Source: https://docs.unity.com/en-us/mps-sdk/matchmaking/mm-rules

Example of a match-level rule that ensures all players in the match are in the same leaderboard tier. Uses the Equality type with source Players.CustomData.ExternalData.Leaderboard.Tier.

```json
"MatchRules": [
    {
        "Name": "Tier",
        "Type": "Equality",
        "Source": "Players.CustomData.ExternalData.Leaderboard.Tier",
        "ExternalData": {
            "Leaderboard": {
                "Id": "my-leaderboard"
            }
        },
        "Not": false,
        "EnableRule": true
    }
]
```
Tokens:
Raw