Mirror Migration Guide

This is a simple guide describing how to convert your Mirror project to Mirage.

Namespace

First of all, Mirror namespace needs to be changed to Mirage. So in your code, replace all:

using Mirror;

with

using Mirage;

Components

Many roles that NetworkManager fulfilled in Mirror were split into multiple simpler components in Mirage, such as NetworkClient, NetworkServer, and NetworkSceneManager. Those classes are no longer static singletons, they are MonoBehaviours instead, so you need to add them to your scene and reference them. NetworkManager in Mirage only serves as a reference holder for server and client.

tip

The easiest way to get started is to right-click in the Hierarchy > Network > NetworkManager. This will create a GameObject with all the necessary components and references already set up.

Accessing Mirage components from NetworkBehaviour

Despite Mirage removing all static states, you can still access the important networking components from within NetworkBehaviour easily. This table shows how to access different components in comparison to Mirror:

Mirror (static)	Mirage (property of NetworkBehaviour)
NetworkServer	Server
NetworkClient	Client
NetworkTime	NetworkTime
doesn't exist	ClientObjectManager
doesn't exist	ServerObjectManager

Network Events Lifecycle

Lifecycle management is no longer based on overrides. Instead, there are many UnityEvents that can be hooked into without direct coupling. They can also be used to hook callbacks via Unity Inspector.

tip

This guide only shows the Mirror counterpart events, but Mirage has more events available, so be sure to check them out as they might be useful.

Server and client events

The table below shows the override method names from Mirror's NetworkManager and the corresponding events from Mirage.

Mirror (override)	Mirage (event)
OnStartServer	NetworkServer.Started
OnServerConnect	NetworkServer.Authenticated
OnServerDisconnect	NetworkServer.Disconnected
OnStopServer	NetworkServer.Stopped
OnClientConnect	NetworkClient.Authenticated
OnClientDisconnect	NetworkClient.Disconnected

For example, this code from Mirror:

using Mirror;

public class MyNetworkManager : NetworkManager 
{
    public override void OnStartServer() 
    {
        // Server started
    }

    public override void OnServerConnect(NetworkConnection conn) 
    {
        // Client connected and authenticated on server
    }

    public override void OnStopServer() 
    {
        // Server stopped
    }

    public override void OnStartClient() 
    {
        // Client started
    }
        
    public override void OnClientConnect(NetworkConnection conn) 
    {
        // Client connected and authenticated
    }
            
    public override void OnClientDisconnect(NetworkConnection conn) 
    {
        // Client disconnected
    }
}

should be changed to:

using Mirage;

public class MyNetworkManager : NetworkManager 
{
    void Awake() 
    {
        Server.Started.AddListener(OnStartServer);
        Server.Authenticated.AddListener(OnServerConnect);
        Server.Stopped.AddListener(OnStopServer);
        Client.Started.AddListener(OnClientStarted);
        Client.Authenticated.AddListener(OnClientConnect);
        Client.Disconnected.AddListener(OnClientDisconnected);
    }

    void OnStartServer() 
    {
        // Server started
    }

    void OnServerConnect(INetworkPlayer conn) 
    {
        // Client connected (and authenticated) on server
    }

    void OnStopServer() 
    {
        // Server stopped
    }

    void OnClientStarted() 
    {
       // Client started
    }

    void OnClientConnect(INetworkPlayer conn) 
    {
        // Client connected
    }

    void OnClientDisconnected(ClientStoppedReason reason) 
    {
        // Client disconnected
    }
}

NetworkBehaviour events

The table below shows the Mirror's NetworkBehaviour override method names on the left and the Mirage events on the right.

Mirror (override)	Mirage (event)
OnStartServer	Identity.OnStartServer
OnStopServer	Identity.OnStopServer
OnStartClient	Identity.OnStartClient
OnStopClient	Identity.OnStopClient
OnStartLocalPlayer	Identity.OnStartLocalPlayer
OnStartAuthority	Identity.OnAuthorityChanged
OnStopAuthority	Identity.OnAuthorityChanged

Let's take this Player class as an example. In Mirror, you would do:

using Mirror;

public class Player : NetworkBehaviour 
{
    public override void OnStartServer() 
    {
        // Player started on server
    }

    public override void OnStartClient() 
    {
        // Player started on client
    }
}

Which should be changed like so in Mirage:

using Mirage;

public class Player : NetworkBehaviour 
{
    void Awake() 
    {
        Identity.OnStartServer.AddListener(OnStartServer);
        Identity.OnStartClient.AddListener(OnStartClient);
    }

    void OnStartServer() 
    {
        // Player started on server
    }

    void OnStartClient() 
    {
        // Player started on client
    }
}

note

Please note that due to timing all event callbacks should be registered in Awake method or via Unity inspector for them to be invoked consistently.

Method Attributes

The table below shows the new attribute names in Mirage.

Mirror	Mirage
[Command]	[ServerRpc]
[TargetRpc]	[ClientRpc(target = Mirage.RpcTarget enum)]
[ServerCallback]	[Server(error = false)]
[ClientCallback]	[Client(error = false)]
doesn't exist	[HasAuthority(error = false)]
doesn't exist	[LocalPlayer(error = false)]

Renames

These fields/properties have been renamed:

Mirror	Mirage
ClientScene.localPlayer	NetworkPlayer.Identity
ClientScene.ready	Client.Player.SceneIsReady
NetworkIdentity.assetId	NetworkIdentity.PrefabHash
NetworkIdentity.netId	NetworkIdentity.NetId
NetworkIdentity.connectionToClient	NetworkIdentity.Owner
NetworkBehaviour.isServer	NetworkBehaviour.IsServer
NetworkBehaviour.connectionToClient	NetworkBehaviour.Owner
NetworkBehaviour.connectionToServer	Removed, use Client.Player instead
NetworkBehaviour.hasAuthority	NetworkBehaviour.HasAuthority
NetworkBehaviour.Identity	NetworkBehaviour.Identity
NetworkBehaviour.netId	NetworkBehaviour.NetId
NetworkBehaviour.isClientOnly	NetworkBehaviour.IsClientOnly
NetworkBehaviour.islocalPlayer	NetworkBehaviour.IsLocalPlayer
NetworkConnection.isReady	NetworkPlayer.SceneIsReady
NetworkConnection.identity	NetworkPlayer.Identity
NetworkServer.active	NetworkServer.Active
NetworkServer.localConnection	NetworkServer.LocalPlayer
NetworkClient.connection	NetworkClient.Player
NetworkTime.time	NetworkTime.Time

Object Management

Registered spawnable prefabs were moved from NetworkManager to the ClientObjectManager component. You can use the Inspector to register all NetworkIdentities via a single click.

Spawning and destroying

Table below shows how to spawn objects in Mirage from NetworkBehaviour:

Mirror	Mirage
NetworkServer.Spawn	ServerObjectManager.Spawn
NetworkServer.Destroy	ServerObjectManager.Destroy