Unity Mirror sample

Welcome to the Unity Mirror sample project! This project demonstrates using the Unity Transport Package (UTP) and Relay with the Mirror Networking API.

  • The Unity Transport Package (UTP) is a low-level networking library that provides a connection-based abstraction layer over UDP sockets with optional functionality such as reliability, ordering, and fragmentation.
  • Relay is a Unity service that facilitates securely connecting players by using a join code style workflow without the need for dedicated game servers or peer-to-peer communication.
  • Mirror is a high-level networking library for the Unity Platform.

You can find the files for UTP in the Assets/UTPTransport directory and the files for Mirror in the Assets/Mirror directory.

Note: This sample project uses code and information from Shrine's Mirror Networking series on YouTube.

Requirements and limitations

The Unity Mirror sample has the following requirements:

Limitations

This sample doesn't work with Game Server Hosting out of the box. However, it's possible to adapt the sample to work with Game Server Hosting (GSH). If you want to adapt the sample to use GSH, remember that Relay is a peer-to-peer-mimicking solution that fills the same space as GSH. As a result, it wouldn't make sense to use Relay and GSH together.

Prerequisites

Before continuing, make sure you have all the prerequisites for using the sample project:

Sample architecture

The Unity Mirror Sample project has two distinct components:

The game client and game server components use Unity and the Mirror Networking API.

Game client

The game client is the executable that players run locally on their machine to connect to the game server and backend services. You can run the game client with Relay or without Relay.

Game server

The game server is the build executable that runs the game server process.

You can run the game server executable locally (for development) or host it with a service such as Game Server Hosting for production.

Note: From the perspective of the Relay service, the game server is the game client of the host player.

Guides

The following sections cover how to interact with, test, and adapt the sample project:

Install the Mirror sample from the Asset Store

Complete the following steps to install the UTP Transport implementation from the sample project into your project. You can also get the sample project code from the repository on GitHub.

  1. Go to the Mirror page in the Asset Store.
  2. Select Add Mirror to My Assets.
  3. Launch the Unity Editor.

    1. Import Mirror using the Package Manager:

      1. Select Window > Package Manager > Packages: My Assets > Mirror > Download/Import.

    2. Import Relay using the Package Manager:

      1. Select Window > Package Manager > Add > Add package from git URL... > "com.unity.services.relay@1.0.4".

    3. Import Jobs using the Package Manager:

      1. Select Window > Package Manager > Add > Add package from git URL... > "com.unity.jobs".

    4. Copy the Assets\UTPTransport directory from the sample project into your project.

    5. Attach the Mirror.NetworkManager component to your GameObject.

    6. Attach the UTP.UtpTransport component to your GameObject.

    7. Assign the UTP.UtpTransport component to the Transport field of the Mirror.NetworkManager component.

    8. Remove the kcp2k.KcpTransport component automatically attached to your GameObject by Mirror.

Test the sample project

Warning: Before testing the sample project, make sure you’ve enabled and set up Relay in the Unity Cloud Dashboard.

To launch two instances of the sample project for testing purposes, complete the following steps:

  1. Open the sample project in the Unity Editor. The project supports Unity 2020.3 or later.
  2. Select ParallelSync > Clones Manager from the editor dropdown. ParallelSync allows you to launch multiple editor instances of the same project.
  3. Select Add new clone.
  4. After you have created the clone, select Open in New Editor.
  5. Select Play in both editor instances.
  6. Select Auth Login on both editor instances. This authenticates with the Unity Authentication Service (UAS) for Relay.

After you have authenticated both editor instances with UAS for Relay, you can test the sample project's UTP transport and Relay functionality.

Use the sample GUI to test the following functionality:

  1. Select Standard Host to launch a server using the UTP transport.
  2. Select Client (without Relay) to connect to a server using the UTP transport.
  3. Select Relay Host to allocate a Relay server.
  4. Select Client (with Relay) to connect to a Relay server.

Note: Ensure that you are using the correct buttons when testing each component

Cross-compile for Linux

You can cross-compile both the game client and game server executables for Linux through the Unity Editor:

  1. Launch the Unity Hub, then select Installs.
  2. Select the gear next to version 2020.3.24f1.
  3. Select Add modules.
  4. Select the Linux Build Support (IL2CPP and Mono) module, then select Install.

After the Linux Build Support module finishes installing, select Linux as a build option within the Unity Editor:

  1. Launch the Unity Editor.
  2. Select File > Build Settings.
  3. Select Linux as the Target Platform.
  4. Select Server build to package a server build. Otherwise, select Build and choose a build location.
Run the game client

You can run the game client component locally as a standalone application or through the Unity Editor.

To run the game client as a standalone application, select the game client executable through the file explorer or through a command-line interface.

To run the game client through the Unity Editor:

  1. Open the Unity Mirror sample project with the Unity Editor (version 2020.3 or later).
  2. Select Play.

Note: When you first open the Unity Mirror sample project, it might take a couple of minutes for Unity to import all the files and packages.

Run the game server

You can run the game server component locally through a command-line interface with the -server argument.

Run the game client and game server together

You can run the game client and game server executables locally by running one as a standalone application and the other through the Unity Editor.

Note: Before running the game client and server, you must create both a server and client build.

For example, to run the game server as a standalone application and the game client through the Unity Editor:

  1. Start the game server through the command-line interface.
  2. Append the -log argument to view logs in real-time.
  3. In the Unity Editor, select Start Client.

Note: The default port for the game server is 7777. Use the -port argument to change the port number.

Adapt the sample project

The Unity Mirror sample project provides sample code for performing the following tasks:

  1. Initialize the Mirror Network Manager
  2. Add Relay functionality
  3. Add UTP Transport functionality
  4. Tie everything together with a custom Network Manager
  5. Expose a GUI for testing
Initialize the Mirror Network Manager

The NetworkManager class in Assets/Mirror/Runtime/NetworkManager.cs is a singleton instance of the Mirror Network Manager. Use the Mirror Network Manager component to manage the networking aspects of multiplayer games, such as game state management, spawn management, and scene management.

Add Relay functionality

The RelayNetworkManager class in Assets/UTPTransport/RelayNetworkManager.cs extends the NetworkManager class with Relay capabilities. It demonstrates how to:

Add UTP functionality

The UtpTransport class in Assets/UTPTransport/UtpTransport.cs is an instance of Mirror.Transport that's compatible with UTP and Relay. It demonstrates how to:

  • Configure the client with a Relay join code
  • Get an allocation from a join code
  • Get Relay region
  • Allocate a Relay server
Create a custom Network Manager

The MyNetworkManager class in Assets/Scripts/MyNetworkManager.cs is an instance of RelayNetworkManager that ties the functionality of the UTP transport for Mirror and the Relay service together.

Expose a user interface

The MenuUI class in Assets/Scripts/MenuUI.cs is responsible for displaying the UI that drives the sample. It interfaces with MyNetworkManager to launch servers and connect clients.

Use UTP Transport for Mirror in your project

This sample has a Unity Transport Package (UTP) transport for Mirror. You can use the code from this sample in your own project by following the instructions in the following sections.

Note: See the Requirements and limitations section before continuing.

Migrate from an existing Transport to the UTP Transport

Complete the following steps if you are already using Mirror and want to migrate from one of the built-in Transports to the UTP Transport.

  1. Launch the Unity Editor.
  2. Locate and open the scene containing the Mirror.NetworkManager component.
  3. Attach the UTP.UtpTransport component to your GameObject.
  4. Assign the UTP.UtpTransport component to the Transport field of the Mirror.NetworkManager component.
  5. Remove the existing Mirror.Transport component from your GameObject.
  6. Configure the parameters of the UTP.UtpTransport component, such as the port and log verbosity, to your satisfaction.
Use Relay with UTP

If you want to use Relay, you must use UTP.RelayNetworkManager instead of Mirror.NetworkManager. This is because UTP.RelayNetworkManager inherits from Mirror.NetworkManager and adds functionality for interacting with the Relay service.

Before you use Relay, you must authenticate with the Unity Authentication Service (UAS). The Relay service requires you to authenticate even if you use your own authentication service.

The following code snippet demonstrates how to authenticate with the Unity Authentication Service:

try
{
   await UnityServices.InitializeAsync();
   await AuthenticationService.Instance.SignInAnonymouslyAsync();
   Debug.Log("Logged into Unity, player ID: " + AuthenticationService.Instance.PlayerId);
}
catch (Exception e)
{
   Debug.LogError(e);
}

After you are authenticated, you can use UTP.RelayNetworkManager to allocate a Relay server or join a Relay server using a join code.

Get help

Having trouble getting started? We can help. Go to the Relay support portal and submit a ticket. Make sure to select Networking Package > Mirror for the ticket category.

Unity logo Documentation
Copyright © 2024 Unity Technologies
"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.