Host migration

Host migration is the act of transferring the lobby host role from one player to another.

This process can occur in the following scenarios:

  • The host of a lobby selects a new host by using UpdateLobby, and then updating the HostId field to the ID of the new host player. The old host remains in the lobby as a non-host player.
  • The host leaves the lobby intentionally without first selecting a new host.
  • Relay integrations removes the host due to inactivity.
  • The host disconnects from the event system for longer than five seconds.

In the scenarios where the host does not specify a new host, the new host is selected randomly from the other players who are currently in the lobby.

Note: If the host is removed due to inactivity, the underlying relay connection is destroyed. To continue receiving automatic disconnects, the new host must create a new relay, and then have the other players join it and set their Allocation ID/ Connection info per the instructions in the Relay integrations section.

Migration data

Host migration data facilitates the transfer of binary game data during host migration events in a lobby. The migration data flow uses the migrationdatainfo endpoint to provide secure, pre-signed URLs for both retrieving and storing binary migration data.

These URLS have the following characteristics:

  • They expire.
  • They have a maximum allowed data length per call.
  • They are player-specific.
  • They only work while the player is in the Lobby host.

Remember to keep migration data compact by only including essential data needed for seamless host transitions, and by avoiding the inclusion of sensitive player information.

Migration data flow

At any time, hosts can request the migration data information and use the URLs to manage binary game data in Lobby:

  1. GET URL: Allows downloading the current migration data. Execute an HTTP GET with the provided URL. When the status is 200 - OK, the response body contains the current game data.
  2. PUT URL: Enables uploading updated migration data. Execute an HTTP PUT with the provided URL. Request body containing the game data and content-type header set to application/octet-stream. The content length must respect the value provided in the URL query parameter.

Note: Implement data validation to verify data integrity after download and before upload.

This approach ensures data integrity and provides a reliable mechanism for preserving lobby state during host transitions. Include version information to handle compatibility between different game versions, as well as retry logic and fallback mechanisms for network failures.

Important: If the URLs expire, call migrationdatainfo again to obtain new URLs. Always check response status codes and handle expired URL scenarios.

Note: The binary data format is entirely controlled by your application. Unity Lobby service treats the migration data as opaque binary content and does not validate or modify the data structure.

Unity logo Documentation
Copyright © 2025 Unity Technologies
"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.