Skip to main content

Seamless Player Migration

Seamless player migration is a technique designed to balance server load efficiently.

Overview​

To reduce the overhead of cross-server communication, most computations are handled locally. In high-density regions, only the most resource-intensive tasks are offloaded to another server, ensuring that the benefits outweigh the costs of server-to-server replication. Interactions between players on different servers are kept minimal, only occurring when players are spread out. Seamless player migration helps achieve this by transferring players to other servers when necessary. The original server simply routes the player’s data packets to the new server, allowing the client to keep the original actors and objects unchanged.

Restrictions​

Player migration requires careful management since it doesn’t complete in a single tick. During the migration, all actors and objects must remain intact—no destruction is allowed. Additionally, interactions with migrating actors or objects are not permitted, and the client must maintain a stable connection throughout the process.

Sequence​

The migration process, from the server where the player logs in to the destination server specified by MigratePlayer, follows this sequence:

Source Server:

  • For each object owned by the migrating player, UNetClusterLibrary::OnMigratingObject is called to save any additional migration data.
  • UNetClusterLibrary::OnMigratingConnection is triggered to save extra migration data for the player's connection.
  • UNetClusterLibrary::OnRouteConnectionReadiness is triggered, signaling that the player’s connection should begin forwarding data packets using UNetClusterLibrary::RouteIncomingData.

Destination Server:

  • Proxy actors are switched to local actors, and UNetClusterLibrary::OnActorRoleSwitched is called.
  • After creating a new connection for the migrating player, UNetClusterLibrary::OnDestinationConnectionReadiness is called, indicating that the connection is ready to accept the player’s network packets.
  • For each object owned by the migrating player, UNetClusterLibrary::OnMigratingObject is called again to restore any saved migration data.
  • UNetClusterLibrary::OnMigratingConnection is triggered to restore the saved migration data for the connection.
  • UNetClusterLibrary::OnMigrationDone is triggered to finalize the migration process.

Source Server:

  • UNetClusterLibrary::OnMigrationDone is triggered to finalize the migration on the source server.

The sequence is similar when migrating from one server (not the login server) to another, as well as from other servers back to the login server.