Class NetworkMigrationManager

A component that manages the process of a new host taking over a game when the old host is lost. This is referred to as "host migration". The migration manager sends information about each peer in the game to all the clients, and when the host is lost because of a crash or network outage, the clients are able to choose a new host, and continue the game.

The old host is able to rejoin the new game on the new host.

The state of SyncVars and SyncLists on all objects with NetworkIdentities in the scene is maintained during a host migration. This also applies to custom serialized data for objects.

All of the player objects in the game are disabled when the host is lost. Then, when the other clients rejoin the new game on the new host, the corresponding players for those clients are re-enabled on the host, and respawned on the other clients. No player state data is lost during a host migration.

This class provides a simple default UI for controlling the behaviour when the host is lost. The UI can be disabled with the showGUI property. There are a number of virtual functions that can be implemented to customize the behaviour of host migration.

Note that only data that is available to clients will be preserved during a host migration. If there is data that is only on the server, then it will not be available to the client that becomes the new host. This means data on the host that is not in SyncVars or SyncLists will not be available after a host migration.

The callback function OnStartServer is invoked for all networked objects when the client becomes a new host.

On the new host, the NetworkMigrationManager uses the function NetworkServer.BecomeNewHost() to construct a networked server scene from the state in the current ClientScene.

The peers in a game with host migration enabled are identified by their connectionId on the server. When a client reconnects to the new host of a game, this connectionId is passed to the new host so that it can match this client with the client that was connected to the old host. This Id is set on the ClientScene as the "reconnectId".

The old host of the game, the one that crashed or lost its network connection, can also reconnect to the new game as a client. This client uses the special ReconnectId of ClientScene.ReconnectIdHost (which is zero).

Inheritance
Object
Object
Component
Behaviour
MonoBehaviour
NetworkMigrationManager
Inherited Members
UnityEngine.Component.guiText
UnityEngine.Component.guiElement
UnityEngine.Component.guiTexture
Namespace: UnityEngine.Networking
Syntax
[AddComponentMenu("Network/NetworkMigrationManager")]
[Obsolete("The high level API classes are deprecated and will be removed in the future.")]
public class NetworkMigrationManager : MonoBehaviour

Properties

client

The client instance that is being used to connect to the host.

This is populated by the Initialize() method. It will be set automatically by the NetworkManager if one is being used.

Declaration
public NetworkClient client { get; }
Property Value
Type Description
NetworkClient

disconnectedFromHost

True is this is a client that has been disconnected from a host.

Declaration
public bool disconnectedFromHost { get; }
Property Value
Type Description
Boolean

hostMigration

Controls whether host migration is active.

If this is not true, then SendPeerInfo() will not send peer information to clients.

Declaration
public bool hostMigration { get; set; }
Property Value
Type Description
Boolean

hostWasShutdown

True if this was the host and the host has been shut down.

Declaration
public bool hostWasShutdown { get; }
Property Value
Type Description
Boolean

matchInfo

Information about the match. This may be null if there is no match.

Declaration
public MatchInfo matchInfo { get; }
Property Value
Type Description
MatchInfo

newHostAddress

The IP address of the new host to connect to.

The FindNewHost utility function will set this address. Methods of choosing the new host that are implemented by users should also set this address.

The default UI button to "Reconnect to New Host" uses this address.

Declaration
public string newHostAddress { get; set; }
Property Value
Type Description
String

offsetX

The X offset in pixels of the migration manager default GUI.

Declaration
public int offsetX { get; set; }
Property Value
Type Description
Int32

offsetY

The Y offset in pixels of the migration manager default GUI.

Declaration
public int offsetY { get; set; }
Property Value
Type Description
Int32

oldServerConnectionId

The connectionId that this client was assign on the old host.

This is the Id that will be set on the ClientScene as the ReconnectId. This Id will be used to identify the client when it connects to the new host.

Declaration
public int oldServerConnectionId { get; }
Property Value
Type Description
Int32

peers

The set of peers involved in the game. This includes the host and this client.

This is populated on clients when they recieve a MsgType.NetworkInfo message from the host. That message is sent when SendPeerInfo() is called on the host.

Declaration
public PeerInfoMessage[] peers { get; }
Property Value
Type Description
PeerInfoMessage[]

pendingPlayers

The player objects that have been disabled, and are waiting for their corresponding clients to reconnect.

There may be multiple pending player GameObjects for each peer. Each will have a different playerControllerId.

The HLAPI treats players and clients as separate GameObjects. In most cases, there is a single player for each client, but in some situations (for example, when there are multiple controllers connected to a console system) there might be multiple player GameObjects for a single connection. When there are multiple players for a single connection, use the playerControllerId property to tell them apart. This is an identifier that is scoped to the connection, so that it maps to the id of the controller associated with the player on that client.

Declaration
public Dictionary<int, NetworkMigrationManager.ConnectionPendingPlayers> pendingPlayers { get; }
Property Value
Type Description
Dictionary<Int32, NetworkMigrationManager.ConnectionPendingPlayers>

showGUI

Flag to toggle display of the default UI.

Declaration
public bool showGUI { get; set; }
Property Value
Type Description
Boolean

waitingReconnectToNewHost

True if this is a client that was disconnected from the host and is now waiting to reconnect to the new host.

Declaration
public bool waitingReconnectToNewHost { get; set; }
Property Value
Type Description
Boolean

waitingToBecomeNewHost

True if this is a client that was disconnected from the host, and was chosen as the new host.

Declaration
public bool waitingToBecomeNewHost { get; set; }
Property Value
Type Description
Boolean

Methods

BecomeNewHost(Int32)

This causes a client that has been disconnected from the host to become the new host of the game.

This starts a server, initializes it with the state of the existing networked objects, and starts a local client so that this client becomes a host. The old NetworkClient instance that was connected to the old host is destroyed.

This will cause OnStartServer to be called on networked objects in the scene.

Any player objects for this peer will automatically be re-added through the local client that was created.

Declaration
public bool BecomeNewHost(int port)
Parameters
Type Name Description
Int32 port

The network port to listen on.
Returns
Type Description
Boolean

True if able to become the new host.

DisablePlayerObjects()

This causes objects for known players to be disabled.

These objects are added to the pendingPlayers list, and will be re-enabled when their clients reconnect.

This happens when the connection to the host of the game is lost.

Declaration
public void DisablePlayerObjects()

FindNewHost(out PeerInfoMessage, out Boolean)

This is a utility function to pick one of the peers in the game as the new host.

This function implements the default host-choosing strategy of picking the peer with the lowest connectionId on the server.

Applications are not required to use this function to choose the new host. They can use any method they want. The choice does not have to be made synchronously, so it is possible to communicate with an external service to choose the new host.

However, the default UI of the NetworkMigrationManager calls into this function.

Declaration
public virtual bool FindNewHost(out PeerInfoMessage newHostInfo, out bool youAreNewHost)
Parameters
Type Name Description
PeerInfoMessage newHostInfo

Information about the new host, including the IP address.
Boolean youAreNewHost

True if this client is to be the new host.
Returns
Type Description
Boolean

True if able to pick a new host.

Initialize(NetworkClient, MatchInfo)

Used to initialize the migration manager with client and match information.

This is called automatically by the NetworkManager from within StartClient() if a NetworkManager is being used with the migration manager.

Declaration
public void Initialize(NetworkClient newClient, MatchInfo newMatchInfo)
Parameters
Type Name Description
NetworkClient newClient

The NetworkClient being used to connect to the host.
MatchInfo newMatchInfo

Information about the match being used. This may be null if there is no match.

LostHostOnClient(NetworkConnection)

This should be called on a client when it has lost its connection to the host.

This will caus the virtual function OnClientDisconnectedFromHost to be invoked. This is called automatically by the NetworkManager if one is in use.

Declaration
public bool LostHostOnClient(NetworkConnection conn)
Parameters
Type Name Description
NetworkConnection conn

The connection of the client that was connected to the host.
Returns
Type Description
Boolean

True if the client should stay in the on-line scene.

LostHostOnHost()

This should be called on a host when it has has been shutdown.

This causes the virtual function OnServerHostShutdown to be invoked. This is called automatically by the NetworkManager if one is in use.

Declaration
public void LostHostOnHost()

OnAuthorityUpdated(GameObject, Int32, Boolean)

A virtual function that is called when the authority of a non-player object changes.

This is called on the host and on clients when the AssignClientAuthority, RemoveClientAuthority and NetworkServer.SpawnWithClientAuthority are used.

Declaration
protected virtual void OnAuthorityUpdated(GameObject go, int connectionId, bool authorityState)
Parameters
Type Name Description
GameObject go

The game object whose authority has changed.
Int32 connectionId

The id of the connection whose authority changed for this object.
Boolean authorityState

The new authority state for the object.

OnClientDisconnectedFromHost(NetworkConnection, out NetworkMigrationManager.SceneChangeOption)

A virtual function that is called when the client is disconnected from the host.

The sceneChange parameter allows the game to choose to stay in the current scene, or switch to the offline scene.

Declaration
protected virtual void OnClientDisconnectedFromHost(NetworkConnection conn, out NetworkMigrationManager.SceneChangeOption sceneChange)
Parameters
Type Name Description
NetworkConnection conn

The connection to the old host.
NetworkMigrationManager.SceneChangeOption sceneChange

How to handle scene changes.

OnPeersUpdated(PeerListMessage)

A virtual function that is called when the set of peers in the game changes.

This happens when a new client connects to the host, a client disconnects from the host, and when players are added and removed from clients.

The list of peers is stored in the member variable peers on the migration manager. This is used when the connection to the host is lost, to choose the new host and to re-add player objects.

Declaration
protected virtual void OnPeersUpdated(PeerListMessage peers)
Parameters
Type Name Description
PeerListMessage peers

The set of peers in the game.

OnServerHostShutdown()

A virtual function that is called when the host is shutdown.

Calling NetworkManager.StopHost() will cause this function to be invoked if there is an active NetworkMigrationManager. Using the Stop Host button of the NetworkManagerHUD will cause this to be called.

Declaration
protected virtual void OnServerHostShutdown()

OnServerReconnectObject(NetworkConnection, GameObject, Int32)

A virtual function that is called for non-player objects with client authority on the new host when a client from the old host reconnects to the new host.

The base class version of this function calls ReconnectObjectForConnection() to hookup the object for the new client.

Declaration
protected virtual void OnServerReconnectObject(NetworkConnection newConnection, GameObject oldObject, int oldConnectionId)
Parameters
Type Name Description
NetworkConnection newConnection

The connection of the new client.
GameObject oldObject

The object with authority that is being reconnected.
Int32 oldConnectionId

The connectionId of this client on the old host.

OnServerReconnectPlayer(NetworkConnection, GameObject, Int32, Int16)

A virtual function that is called on the new host when a client from the old host reconnects to the new host.

The base class version of this function calls ReconnectPlayerForConnection() to hookup the new client.

ReconnectPlayerForConnection does not have to be called from within this function, it can be done asynchronously.

Declaration
protected virtual void OnServerReconnectPlayer(NetworkConnection newConnection, GameObject oldPlayer, int oldConnectionId, short playerControllerId)
Parameters
Type Name Description
NetworkConnection newConnection

The connection of the new client.
GameObject oldPlayer

The player object associated with this client.
Int32 oldConnectionId

The connectionId of this client on the old host.
Int16 playerControllerId

The playerControllerId of the player that is re-joining.

OnServerReconnectPlayer(NetworkConnection, GameObject, Int32, Int16, NetworkReader)

A virtual function that is called on the new host when a client from the old host reconnects to the new host.

The base class version of this function calls ReconnectPlayerForConnection() to hookup the new client.

ReconnectPlayerForConnection does not have to be called from within this function, it can be done asynchronously.

Declaration
protected virtual void OnServerReconnectPlayer(NetworkConnection newConnection, GameObject oldPlayer, int oldConnectionId, short playerControllerId, NetworkReader extraMessageReader)
Parameters
Type Name Description
NetworkConnection newConnection

The connection of the new client.
GameObject oldPlayer

The player object associated with this client.
Int32 oldConnectionId

The connectionId of this client on the old host.
Int16 playerControllerId

The playerControllerId of the player that is re-joining.
NetworkReader extraMessageReader

Additional message data (optional).

ReconnectObjectForConnection(NetworkConnection, GameObject, Int32)

This re-establishes a non-player object with client authority with a client that is reconnected. It is similar to NetworkServer.SpawnWithClientAuthority().

This is called by the default implementation of OnServerReconnectObject.

Declaration
public bool ReconnectObjectForConnection(NetworkConnection newConnection, GameObject oldObject, int oldConnectionId)
Parameters
Type Name Description
NetworkConnection newConnection

The connection of the new client.
GameObject oldObject

The object with client authority that is being reconnected.
Int32 oldConnectionId

This client's connectionId on the old host.
Returns
Type Description
Boolean

True if the object was reconnected.

ReconnectPlayerForConnection(NetworkConnection, GameObject, Int32, Int16)

This re-establishes a player object with a client that is reconnected. It is similar to NetworkServer.AddPlayerForConnection(). The player game object will become the player object for the new connection.

This is called by the default implementation of OnServerReconnectPlayer.

using UnityEngine;
using UnityEngine.Networking;

class MyMigrationManager : NetworkMigrationManager
{
   protected override void OnServerReconnectPlayer(NetworkConnection newConnection, GameObject oldPlayer, int oldConnectionId, short playerControllerId)
   {
       Debug.Log("Reconnecting oldPlayer:" + oldPlayer);
       ReconnectPlayerForConnection(newConnection, oldPlayer, oldConnectionId, playerControllerId);
   }
}
Declaration
public bool ReconnectPlayerForConnection(NetworkConnection newConnection, GameObject oldPlayer, int oldConnectionId, short playerControllerId)
Parameters
Type Name Description
NetworkConnection newConnection

The connection of the new client.
GameObject oldPlayer

The player object.
Int32 oldConnectionId

This client's connectionId on the old host.
Int16 playerControllerId

The playerControllerId of the player that is rejoining.
Returns
Type Description
Boolean

True if able to re-add this player.

Reset(Int32)

Resets the migration manager, and sets the ClientScene's ReconnectId.

Declaration
public void Reset(int reconnectId)
Parameters
Type Name Description
Int32 reconnectId

The connectionId for the ClientScene to use when reconnecting.

SendPeerInfo()

This sends the set of peers in the game to all the peers in the game.

This is called automatically by the NetworkManager if one is active. It happens when clients connect to and disconnect from the server, and when players are added and removed from clients. The function SendPeers() udpates all clients with the information about which client owns which objects. It is automatically called when players are added and removed via the NetworkManager, but there is no hook in the NetworkManager when non-player client authority objects are added and removed. SendPeerInfo() is NOT called automatically. It is up to user code to call SendPeerInfo() when they want to update the set of client-owned objects.

Declaration
public void SendPeerInfo()