Host migration in Asteroids
This sample demonstrates an implementation of host migration in Netcode for Entities using the Asteroids sample as a base.
Note
Host migration is in an early stage of development and currently has a limited scope. This sample demonstrates potential API usage in conjunction with existing Unity services, but isn't optimized for performance or scale.
For more general information about host migration in Netcode for Entities, refer to the host migration page.
Requirements
- The Asteroids sample project requires Unity 6 (at least 6.0.23f1), because it uses new features in both the Dedicated Server and Multiplayer Play Mode packages. The host migration API itself, however, works in Unity 2022.3 like the Netcode for Entities package itself does.
- This sample project needs to be linked to a project in the Unity Cloud Dashboard. It needs to be configured to use Player Authentication, Relay, and Lobby services.
Sample steps
- Create a new Unity project and link it to a project ID as described in the requirements.
- Optionally, navigate to Lobby > Config in the Unity Cloud Dashboard and change the Disconnect Removal Timeout to 10s and Disconnect Host Migration Time to 5s.
- Open the Multiplayer Play Mode window by navigating to Window > Multiplayer Play Mode and start two virtual player instances. Set both to Client and Server roles.
- Enter Play mode in the Frontend scene (inside Assets/Samples/HelloNetcode/1_Basics/01_BootstrapAndFrontend) and select the Asteroids sample in the drop-down list. Select the Enable Host Migration toggle.
- If you change the lobby name, make sure it's also changed on all other instances.
- To spawn the player ship press the spacebar key
- Pick the Editor or one of the virtual players to run as the initial host and select Start Client & Server.
- Wait for the host migration statistics to appear in the lower right corner. When they appear, the lobby connection is ready to handle host migrations.
- The lower right corner also displays whether the connected instance is a server or client.
- In the other instances, select Join Existing Game.
- Select the Return To Main Menu button in the corner on the host to exit the game and lobby and trigger a host migration.
- To trigger a host migration with a timeout it's better to use a standalone build and terminate the player
- One of the other instances will become the host and display migration update statistics in the corner. Other instances will join it automatically.
- The host data should have been migrated between hosts. All the asteroids and ship positions will be the same as they were before, the ship colors will also be the same and stay that way when the ship is destroyed and re-spawns.
Ensuring that state is migrated properly in Asteroids
- A color is applied to each player ship. To ensure that this color is kept consistent across host migration, you need to associate the player color to a connection and use a special ghost prefab to contain the host data that needs to be migrated.
- The server assigns a
PlayerColor
component to each connection when it's accepted. When a player ship owned by that connection spawns, the color component is added to the ship. - When a migration occurs, all the user components on the connection entity are migrated as well, including the
PlayerColor
component. - A
PlayerColorNext
server-only ghost component is present on a specialHostConfig
ghost entity. This ghost only contains server data and thus has nothing to replicate to clients. TheHostConfig
entity stores which color will be assigned to the next client connection (an integer incrementing from 1 until it wraps after 12 connections, refer toUnity.NetCode.NetworkIdDebugColorUtility
helper class).
- The server assigns a
- When a reconnected connection is detected on the client, it's placed in-game by adding a
NetworkStreamInGame
component to it when theLevelComponent
has been created. This means that the client has configured the level according to the server command and is ready to start play. Refer toAsteroids.Client.HostMigrationSystem
. - The server automatically spawns extra asteroids when their number is lower than the limit configured for the level. During host migration this system needs to pause and wait until the host migration data has been deployed, or it will spawn the full amount of asteroids before the host migration process also spawns the asteroids included in the host data. It does this by exiting the system's update loop when a
HostMigrationInProgress
component is detected.