Session host migration
Learn about changing session ownership, including host election and data migration.
Read time 2 minutesLast updated 14 hours ago
In the sessions system, migration involves two aspects: host election, and data migration. The session system exposes to notify you about changes in session ownership and migration status:
- is raised when a new host is elected.
ISession.SessionHostChanged - is raised when data migration has completed.
ISession.SessionMigrated
Host election
Host election allows changing the session’s host. The current host can start this by updating the session’s assigned host ID. For the change to take effect, save all session properties so the update propagates to all participants.Note
Host election doesn't migrate any network-synchronized data.
Data migration
Note
The session system includes a default data migration implementation only for Netcode for Entities. If you use Netcode for GameObjects, use Distributed Authority to handle migration-related operations.
Important
Starting with Multiplayer Services SDK version 1.2, the default network handler implementation for Netcode for Entities automatically creates client and server worlds if none are available when starting a network connection through sessions.Older versions of the MPS SDK require you to create your Netcode for Entities client and server worlds before you can create or join a Multiplayer Services session. When you first add the Netcode for Entities package to your project, the default bootstrap automatically creates the client and server worlds at startup.For more advanced use cases, use a custom network handler to override the default integration with Netcode for Entities.
WithHostMigrationIMigrationDataHandlerIMigrationDataHandlerImportant
Enabling the host data migration on a session doesn't set up the required entities component in your world. You must set up the required components manually, refer to Netcode for Entities for more information.
EnableHostMigrationWithHostMigration- Configure the interval for automatic Netcode snapshot generation.
- Set a timeout for snapshot uploads.
- Provide a custom if
IMigrationDataHandlerdoesn’t fit your use case.EntitiesMigrationDataHandler - Defaults: a 3-second snapshot interval and a 5-second upload timeout.
GetHostMigrationDataAsyncSetHostMigrationDataAsyncIMigrationDataHandlerUsing Relay
Added optional parameterpreserveRegionRelayOptionsWithRelayNetworkStartRelayNetworkExamples
Example: Creating a custom IMigrationData
Implement a data migration handler.Use the custom implementation with the sessions.public class CustomDataHandler : IMigrationDataHandler{ public byte[] Generate() { // implement a process to serialize data based on the network component in the scene / world return new byte[42]; } public void Apply(byte[] migrationData) { // implement a process to de-serialize data and apply in current scene / server world Assert.AreEqual(42, migrationData.Length); }}
public Task CreateOrJoinSessionWithDataMigartionEnabled(string sessionId){ var sessionOptions = new SessionOptions().WithHostMigration(migrationDataHandler: new CustomDataHandler()); var session = await MultiplayerService.Instance.CreateOrJoinSessionAsync(sessionId, options)}
Note
Enabling the host data migration on a session doesn't set up the required entities component in your world. Set up the required components manually. Refer to Netcode for Entities for more information.
EnableHostMigrationExample: Electing a new Host
The following code snippet demonstrates how to elect a givenplayerAfter setting thepublic Task ElectPlayerAsHostAsync(string playerId){ _session.AsHost().Host = player.Id; return _session.AsHost().SavePropertiesAsync();}
session