[email protected]

## [1.5.1] - 2025-05-06

### Added

* Experimental host migration feature added, enabled with the ENABLE_HOST_MIGRATION define but otherwise hidden.
* With ENABLE_HOST_MIGRATION defined, when a client reconnects to a server after disconnecting the connection entity on both sides will receive a `NetworkStreamIsReconnected` component. An internal unique ID is added to connections to track this behaviour.

### Changed

* IsReconnected split into NetworkStreamIsReconnected for reconnected connections and IsMigrated for re-spawned ghosts (Host Migration).

### Fixed

* An issue with Mutiplayer PlayModeTool window, throwing exceptions when docked after a domain reload. The issue was due to because of an access to `EditorPrefs` and `Application.productName` while restoring the window state.
* Issue where, during host migration, ghosts could be migrated with a 0 id and type. Causing various issues when instantiated on the new host.
* Crash which could happen after host migrations when the server is deploying the host migration data.
* Issue with prespawn prefab entity list initialization after a host migration, the ordering of the prespawn ghosts could be shifted by one because of the internal `PrespawnSceneList` entity prefab creation. This would result in *invalid ghost type X (expected X+1)* off by one style errors.

Author: Unity Technologies

.signature

@@ -1 +1 @@
-{"timestamp":1745399088,"signature":"W9rEhPHEX+yUrTBWT/Yn03xwiY/qsK+O/dHpXPH0lWYNelzYtrq4MaPxM902U5BGoydqa/HEtmxzg7Stht4y2o/VYtrhB2/ZS/NSdvJVnujw9DO93Hdz9xQ5TAmCr2lrvId1l2ZWIf3fwuMg8Uy0eTN6PckU+eM8WVp9h4h8724wd9MOdeHdJrN7aDlIAsymNSUeFVr35QwmMNbCj+POjfbfqy5n2I72+CMVkPXvtqjycUVU/i+xlG3n6ZHdh5POW/nrDObMcIy8HcEp5M6RiWRtqxGx5gN2Vf3l1HI0DNfUAtSTQgnXhQRY3gE+NJiM8AnkzgzFmCxOr5AqPrm9v//ymCkFbkTXx0v5itT/mR7eBhkCoALsAre0iFT57emvJXnZq051O2q8cstaUPcde3EJPNmZUHr1LbNYpK6ZVRyd7lANDXreddHrcf7MlocziYKZt77OoparrNuP+ZqxiZQSv6h7vrNGU8lhoGKQvZAJM2oEE3ZSdWDPPRdk8YRU","publicKey":"LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQm9qQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FZOEFNSUlCaWdLQ0FZRUFzdUhXYUhsZ0I1cVF4ZEJjTlJKSAordHR4SmoxcVY1NTdvMlZaRE1XaXhYRVBkRTBEMVFkT1JIRXNSS1RscmplUXlERU83ZlNQS0ZwZ1A3MU5TTnJCCkFHM2NFSU45aHNQVDhOVmllZmdWem5QTkVMenFkVmdEbFhpb2VpUnV6OERKWFgvblpmU1JWKytwbk9ySTRibG4KS0twelJlNW14OTc1SjhxZ1FvRktKT0NNRlpHdkJMR2MxSzZZaEIzOHJFODZCZzgzbUovWjBEYkVmQjBxZm13cgo2ZDVFUXFsd0E5Y3JZT1YyV1VpWXprSnBLNmJZNzRZNmM1TmpBcEFKeGNiaTFOaDlRVEhUcU44N0ZtMDF0R1ZwCjVNd1pXSWZuYVRUemEvTGZLelR5U0pka0tldEZMVGdkYXpMYlpzUEE2aHBSK0FJRTJhc0tLTi84UUk1N3UzU2cKL2xyMnZKS1IvU2l5eEN1Q20vQWJkYnJMbXk0WjlSdm1jMGdpclA4T0lLQWxBRWZ2TzV5Z2hSKy8vd1RpTFlzUQp1SllDM0V2UE16ZGdKUzdGR2FscnFLZzlPTCsxVzROY05yNWdveVdSUUJ0cktKaWlTZEJVWmVxb0RvSUY5NHpCCndGbzJJT1JFdXFqcU51M3diMWZIM3p1dGdtalFra3IxVjJhd3hmcExLWlROQWdNQkFBRT0KLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg"}
+{"timestamp":1746690456,"signature":"bCmoScfUziQEIVPEEIAWoaNL/hjF9HCIdrCY5071qHEiD7upspLf8d3LMsi3LelSuIlWXf82eXsJk8QOWwd6+ldlvNGeTpVGM31sGbhy5zyGGcltSgT4WXk0aYSwKQERwVrB8jckyuByoptTX5JgfweoRvykWVeZWH/Dts67qUhBjSIku3zE3OLjKAucZAQ37nBlIfkk2j9ZWehGzXHmYABX2XPnext0d6/Q4gO5puYKwGPC8oSl/ZXNOGfYok5e3FC0LcFQ0LFju6xSVdfInxX34AHPblQl/2w3PYkmz8dsNn7SlDrg0qfkXznSimJVXq1Vhzl3ZF6GgA+2qO7mtfA8sNfPhKhqfuzArz1Cm8mxJyYD3FhhOhHyEwiKYT8gYLiuZi/o1t7lk9Fja10igqPOv0WwaD0KDqry06tEH4iB+tmr3ahdHasVzGuwoPSBQjLSWaX8cufAJh+B5XiS51lbJ4tJd4FlCfyhDVc2KLF/YfTJJlIvg8Y4YF0ClydK","publicKey":"LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQm9qQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FZOEFNSUlCaWdLQ0FZRUFzdUhXYUhsZ0I1cVF4ZEJjTlJKSAordHR4SmoxcVY1NTdvMlZaRE1XaXhYRVBkRTBEMVFkT1JIRXNSS1RscmplUXlERU83ZlNQS0ZwZ1A3MU5TTnJCCkFHM2NFSU45aHNQVDhOVmllZmdWem5QTkVMenFkVmdEbFhpb2VpUnV6OERKWFgvblpmU1JWKytwbk9ySTRibG4KS0twelJlNW14OTc1SjhxZ1FvRktKT0NNRlpHdkJMR2MxSzZZaEIzOHJFODZCZzgzbUovWjBEYkVmQjBxZm13cgo2ZDVFUXFsd0E5Y3JZT1YyV1VpWXprSnBLNmJZNzRZNmM1TmpBcEFKeGNiaTFOaDlRVEhUcU44N0ZtMDF0R1ZwCjVNd1pXSWZuYVRUemEvTGZLelR5U0pka0tldEZMVGdkYXpMYlpzUEE2aHBSK0FJRTJhc0tLTi84UUk1N3UzU2cKL2xyMnZKS1IvU2l5eEN1Q20vQWJkYnJMbXk0WjlSdm1jMGdpclA4T0lLQWxBRWZ2TzV5Z2hSKy8vd1RpTFlzUQp1SllDM0V2UE16ZGdKUzdGR2FscnFLZzlPTCsxVzROY05yNWdveVdSUUJ0cktKaWlTZEJVWmVxb0RvSUY5NHpCCndGbzJJT1JFdXFqcU51M3diMWZIM3p1dGdtalFra3IxVjJhd3hmcExLWlROQWdNQkFBRT0KLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg"}

CHANGELOG.md

@@ -1,6 +1,24 @@
 ---
 uid: changelog
 ---
+## [1.5.1] - 2025-05-06
+
+### Added
+
+* Experimental host migration feature added, enabled with the ENABLE_HOST_MIGRATION define but otherwise hidden.
+* With ENABLE_HOST_MIGRATION defined, when a client reconnects to a server after disconnecting the connection entity on both sides will receive a `NetworkStreamIsReconnected` component. An internal unique ID is added to connections to track this behaviour.
+
+### Changed
+
+* IsReconnected split into NetworkStreamIsReconnected for reconnected connections and IsMigrated for re-spawned ghosts (Host Migration).
+
+### Fixed
+
+* An issue with Mutiplayer PlayModeTool window, throwing exceptions when docked after a domain reload. The issue was due to because of an access to `EditorPrefs` and `Application.productName` while restoring the window state.
+* Issue where, during host migration, ghosts could be migrated with a 0 id and type. Causing various issues when instantiated on the new host.
+* Crash which could happen after host migrations when the server is deploying the host migration data.
+* Issue with prespawn prefab entity list initialization after a host migration, the ordering of the prespawn ghosts could be shifted by one because of the internal `PrespawnSceneList` entity prefab creation. This would result in *invalid ghost type X (expected X+1)* off by one style errors.
+
 
 ## [1.5.0] - 2025-04-22
 

Documentation~/TableOfContents.md

@@ -25,6 +25,15 @@
     * [Prediction switching](prediction-switching.md)
     * [Prediction edge cases and known issues](prediction-details.md)
   * [Physics](physics.md)
+  * [Host migration](host-migration/host-migration.md)
+    * [Introduction to host migration](host-migration/host-migration-intro.md)
+    * [Host migration API and components](host-migration/host-migration-api.md)
+    * [Add host migration to your project](host-migration/add-host-migration.md)
+      * [Host migration requirements](host-migration/host-migration-requirements.md)
+      * [Host migration systems and data](host-migration/host-migration-systems.md)
+      * [Lobby and Relay integration](host-migration/lobby-relay-integration.md)
+    * [Limitations and known issues](host-migration/host-migration-limitations.md)
+  * [Ghost type templates](ghost-types-templates.md)
 * [Testing and debugging your game](debugging.md)
   * [Logging](logging.md)
   * [Using the PlayMode Tool](playmode-tool.md)
@@ -36,6 +45,7 @@
   * [Data compression](compression.md)
 * [Samples](samples.md)
   * [Networked cube](networked-cube.md)
+  * [Host migration in Asteroids](host-migration/host-migration-sample.md)
 * [Reference](reference.md)
   * [Netcode-specific components and types](entities-list.md)
   * [Netcode Project Settings reference](project-settings.md)

Documentation~/creating-multiplayer-gameplay.md

@@ -10,3 +10,4 @@ Create multiplayer gameplay in Netcode for Entities.
 | **[Interpolation and extrapolation](interpolation.md)**| Use interpolation and extrapolation in your game to minimize the effects of adverse network conditions on gameplay. |
 | **[Prediction](prediction.md)**| Use prediction to manage latency in your game. |
 | **[Physics](physics.md)**| The Netcode package has some integration with Unity Physics which makes it easier to use physics in a networked game. The integration handles interpolated ghosts with physics, and support for predicted ghosts with physics. |
+| **[Host migration](host-migration/host-migration.md)** | Use host migration to transfer the host role to a client in the same session when the current host leaves. |

Documentation~/host-migration/add-host-migration.md

@@ -0,0 +1,13 @@
+# Add host migration to your project
+
+> [!NOTE]
+> Host migration is an experimental feature so the API and implementation can change in the future. By default it's not exposed, enable it by adding the `ENABLE_HOST_MIGRATION` define in the __Scripting Define Symbols__ in the __Player__ tab of the project settings.
+
+Understand the requirements, systems, and integrations involved in adding host migration to your project.
+
+| **Topic**                       | **Description**                  |
+| :------------------------------ | :------------------------------- |
+| **[Host migration requirements](host-migration-requirements.md)** | Understand the requirements for using host migration in a project and which platforms are supported. |
+| **[Host migration considerations](host-migration-considerations.md)** | A project which supports migration of the server data to a new server requires certain design considerations.
+| **[Host migration systems and data](host-migration-systems.md)** | Set up host migration systems in your project to enable host migration in a client hosted networking experience. |
+| **[Lobby and Relay integration](lobby-relay-integration.md)**  | Integrate with Unity Lobby and Unity Relay to enable host migration in Netcode for Entities. |

Documentation~/host-migration/host-migration-api.md

@@ -0,0 +1,40 @@
+# Host migration API and components
+
+> [!NOTE]
+> Host migration is an experimental feature so the API and implementation can change in the future. By default it's not exposed, enable it by adding the `ENABLE_HOST_MIGRATION` define in the __Scripting Define Symbols__ in the __Player__ tab of the project settings.
+
+Understand the host migration API, components, and component options.
+
+## Host migration API
+
+| `HostMigration` class | Description |
+|-|-|
+| `GetHostMigrationData(world, data)` | Get the current host migration data from the host migration system in the given server world and copy it into the native list. The list is resized to fit the data if required. |
+| `TryGetHostMigrationData(world, data, size)` | Get the current host migration data from the host migration system in the given server world and copy it into the buffer. The amount of data copied is placed in the size variable. If the buffer is too small, the required size will be in the size variable. |
+| `SetHostMigrationData(world, data)` | Deploy the given migration data in the target server world. This would be the data downloaded from the lobby service but with a world manually created. |
+| `ConfigureClientAndConnect(clientWorld, driverConstructor, serverEndpoint)` | Connect to a specific endpoint after a host migration. The client driver store and network driver will be reconfigured to use the latest relay data. |
+| `MigrateDataToNewServerWorld(driverConstructor, migrationData)` | Create a server world and populate it with the given host migration data blob (downloaded from lobby). A relay allocation will be created and the lobby updated with latest join code. The local client will call the above API and connect directly to the new server world via IPC driver interface. |
+
+## Host migration components
+
+| Components | Description |
+|-|-|
+| `NetworkStreamIsReconnected` | This component is added to all connections on clients and the server so that they can react to being reconnected. The spawned ghosts on the new host also receive this component, so if there are any fixes needed you can query against this component. |
+| `EnableHostMigration` | Enable the host migration system. When enabled, the system collects host migration data at the interval specified in `HostMigrationConfig`, and updates the last update time in `HostMigrationStats`. |
+| `HostMigrationInProgress` | This component is used to detect when a host migration is in progress and when it's complete. |
+| `HostMigrationConfig` | A singleton component that exposes a few options to modify in the host migration system. |
+| `HostMigrationStats` | A few statistics about the lobby operations like the data blob size. This component also contains the last update time of the host migration data which can be used to see when it's time to upload it again.|
+
+### `HostMigrationConfig` component options
+
+The `HostMigrationConfig` component has the following options:
+
+* `StorageMethod`: Switch between using plain JSON or binary serializers from the serialization package, or the `DataWriter` buffer which is compressed and Base64 encoded (the default).
+* `StoreOwnGhosts`: Enable or disable saving of local client-owned ghosts on the host. When the host disconnects this client also disappears, so this data might be unnecessary (defaults to false).
+* `MigrationTimeout`: How long to wait for ghost prefabs to be loaded (defaults to 10 seconds).
+* `ServerUpdateInterval`: At what interval should host migration data be updated. The lowest possible value is 1 second because of rate limits (default is 2 seconds).
+
+## Additional resources
+
+* [Introduction to host migration](host-migration-intro.md)
+* [Add host migration to your project](add-host-migration.md)

Documentation~/host-migration/host-migration-considerations.md

@@ -0,0 +1,25 @@
+# Project considerations for supporting host migration
+
+> [!NOTE]
+> Host migration is an experimental feature so the API and implementation can change in the future. By default it's not exposed, enable it by adding the `ENABLE_HOST_MIGRATION` define in the __Scripting Define Symbols__ in the __Player__ tab of the project settings.
+
+When server data is migrated to a new server the normal flow for setting up ghosts and players / connections is different and might require certain consideration for making it work. Anything not migrated over will start from defaults after unity scenes have been loaded in the server world and the normal scene will be in whatever configuration it was on the client before he took over hosting duties. Reconnecting clients connecting might not need to initialize like new clients as their data might have been migrated, and so on.
+
+## `NetworkStreamInGame` considerations
+
+[`NetworkStreamInGame`](https://docs.unity3d.com/Packages/com.unity.netcode@latest?subfolder=/api/Unity.NetCode.NetworkStreamInGame.html) requires special consideration on the client. After a migration, the server creates existing and new connections in-game after all subscenes have been loaded. No ghosts are respawned before at least one connection is in-game (this is usually the local client that immediately connects after the local server starts). On the client side, however, it can be difficult to tell when it's safe to start streaming ghost snapshots and `NetworkStreamInGame` needs to be added manually. To treat re-connections differently, you can check if the connection on the client has the `NetworkStreamIsReconnected` component added. If there's no difference in the connection flow depending on re-connections or new connections then nothing needs to be done. For example, if the server is sending a `LoadLevel` style RPC to the client after which it will place itself in game.
+
+## Migrated data can be invalid on the new server
+
+If there are entity variables in ghost components or any data that won't have a valid reference when it's been moved between hosts, then these instances need to be fixed after a migration. This can be done by querying against particular components on ghost entities with the `IsMigrated` tag added to identify respawned ghosts. Some other data needs to added instead or in addition to this to help correct these variables to reflect the new host state. For example, the entity could be looked up via some other component data (ID or name but not ghost ID, see note below) used to identify it.
+
+## Waiting until migration is completed
+
+Certain systems could start running as soon as a new server world is created and start initializing variables which will then be overwritten or become invalid after the host migration data has been deployed in the world. For example, if a system is ensuring certain conditions are met (querying for certain entities), these conditions are met in the host migration data but might be enforced before the host migration data is ready. Thus things might be duplicated or otherwise invalid.
+
+To ensure things settle properly after a host migration, these systems should check if there is a singleton `HostMigrationInProgress` component in the world. If this is present the system could early out until it has disappeared. This component is created immediately after world creation so this should ensure things are stable after the migration is deployed.
+
+## Dealing with the client's player entity
+
+When clients reconnect to a new host there might be special considerations for dealing with the player entity owned in the previous host session. Since the player is included in the host migration data, there's no need to spawn it again. As would normally happen when the client connects, possibly after some initial init/handshake with the server. There are multiple ways to deal with that, for example if the server saves information about the client on the  connection entity (like a tag component with `PlayerSpawned`) then this information will be migrated as well and seeing that tag could skip initialization of the player for that client. The `GhostOwner` component will then also be updated and inputs should work correctly without any intervention.
+