[email protected]

## [1.6.1] - 2025-05-28

### Added

* Two new entity command buffer systems that run at the beginning and end of the `PredictedSimulationSystemGroup` respectively: `BeginPredictedSimulationCommandBufferSystem` and `EndPredictedSimulationCommandBufferSystem`.
* A new internal `PredictedSpawningSystemGroup`, running after the `EndPredictedSimulationCommandBufferSystem`, created to guarantee that when a new snapshot is received from server, all new ghosts are spawned and ready to receive new data.
* New documentation regarding the NetworkDriverStore architecture, setup and how to use it in conjunction with Unity.Relay.
* 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.
* The ability to define a smaller `GhostSystemConstants.SnapshotHistorySize` value via compiler define `NETCODE_SNAPSHOT_HISTORY_SIZE_6` or `NETCODE_SNAPSHOT_HISTORY_SIZE_16`. These values are well suited for larger scale use-cases where server memory is constrained, and snapshot sends of individual ghosts are relatively infrequent.
* Support for combining Ghost Relevancy with Ghost Importance Scaling via new `PrioChunks.isRelevant` field, [enabling a fast-path for relevancy calculations](https://docs.unity3d.com/Packages/com.unity.netcode@latest?subfolder=/manual/optimizations.html#relevancy-fast-path-via-importance-scaling).
* Analytics to netcode tools to better understand their usage.

### Changed

* **Behaviour Breaking Change:** Predicted spawned ghosts for partial ticks skip restoring the state from the backup (and instead continue prediction from their spawn state) when the last backup state tick is identical to the spawn tick, as no data has changed.
* **Behaviour Breaking Change:** Reduced the complexity (and performance overhead) of the `GhostCount.GhostCountOnServer` calculations internally. Note that this value is (and always has been) an approximation.
* IsReconnected split into NetworkStreamIsReconnected for reconnected connections and IsMigrated for re-spawned ghosts (Host Migration).
* Moved host migration related types into a `Unity.Netcode.HostMigration` namespace, renamed the `HostMigration` class to `HostMigrationUtility` so it works in the new namespace.
* Prespawn ghost IDs will now be preserved between host migrations
* Client connection `NetworkIDs` are now preserved between host migrations.

### Fixed

* **Behaviour Breaking Change:** Incorrect state serialized inside the `SnapshotDataBuffer` for predicted spawned ghost on the client when spawned inside the prediction loop. The `PredictedGhostSpawnSystem` is now updated also as part of the prediction loop (inside the `PredictedSpawningSystemGroup`) to ensure that any predicted spawned ghosts on the client are correctly initialized at the tick they are spawned, and not with partial tick state.
* Issue where predicted spawned ghosts re-simulated from the wrong tick when configured to rollback to their `spawnTick` and are spawned inside the prediction loop. They are now restored using the corrected full tick state, rather than the erroneous partial tick state.
* Enable creating and initializing server drivers when using WebGL to enable self-hosting cases using relay. Many methods were under conditional compilation flags and removed from the WebGL build and not usable outside the editor.
* All the unmanaged systems present in the FixedStepSimulationSystemGroup that have a direct or indirect update dependency to the PhysicsSystemGroup are now correctly moved to the PredictedFixedStepSimulationSystemGroup. This is a **Behaviour Change** in respect the previous versions, where all the unmanaged systems continued to stay inside the fixed update group, regardless of the dependency of update order.
* 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.
* The prediction loop will no longer rollback too many times when one ghost is switched from predicted to interpolated, and later switched back to predicted, when that ghost is the only predicted ghost.
* If you update multiple packages, create a new section with a new header for the other package.
* The client packet dump was not being written to the `EnablePacketLogging.NetDebugPacketCache` field, thus were not usable by users and other netcode call-sites (like the `NetworkStreamReceiveSystem`).
* `SnapshotHistorySize` values below 32 uncovered an issue where a ghost chunk being written would write over its snapshot history entries for currently-in-flight snapshots, leading to a cycle of never being able to fetch a valid baseline, in perpetuity. The fix for this requires us to stall the send of this ghost chunk if the in-flight queue is full, until the in-flight snapshots are assumed to have either arrived or been lost/dropped.
* Buffer serialization errors caused by incorrect pointer stepping when ghost fields are not present (i.e. surrounding `GhostComponentSerializer.State.HasGhostFields`).
* Buffer serialization errors caused by missing change mask invalidation when `SendToOwnerType` or `GhostSendType` conditionally prevented sending of the buffer.
* Readded `UsePreSerialization` to the `GhostAuthoringComponent` inspector that was accidentally removed.

### Obsolete

* Prefer `BatchScaleImportanceDelegate` to `ScaleImportanceFunction` as the latter significantly reduces the total number of function pointer calls.

Author: Unity Technologies

.buginfo

@@ -0,0 +1,4 @@
+system: jira
+server: jira.unity3d.com
+project: N4EBUG
+issuetype: Bug

.signature

@@ -1 +1 @@
-{"timestamp":1746690456,"signature":"bCmoScfUziQEIVPEEIAWoaNL/hjF9HCIdrCY5071qHEiD7upspLf8d3LMsi3LelSuIlWXf82eXsJk8QOWwd6+ldlvNGeTpVGM31sGbhy5zyGGcltSgT4WXk0aYSwKQERwVrB8jckyuByoptTX5JgfweoRvykWVeZWH/Dts67qUhBjSIku3zE3OLjKAucZAQ37nBlIfkk2j9ZWehGzXHmYABX2XPnext0d6/Q4gO5puYKwGPC8oSl/ZXNOGfYok5e3FC0LcFQ0LFju6xSVdfInxX34AHPblQl/2w3PYkmz8dsNn7SlDrg0qfkXznSimJVXq1Vhzl3ZF6GgA+2qO7mtfA8sNfPhKhqfuzArz1Cm8mxJyYD3FhhOhHyEwiKYT8gYLiuZi/o1t7lk9Fja10igqPOv0WwaD0KDqry06tEH4iB+tmr3ahdHasVzGuwoPSBQjLSWaX8cufAJh+B5XiS51lbJ4tJd4FlCfyhDVc2KLF/YfTJJlIvg8Y4YF0ClydK","publicKey":"LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQm9qQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FZOEFNSUlCaWdLQ0FZRUFzdUhXYUhsZ0I1cVF4ZEJjTlJKSAordHR4SmoxcVY1NTdvMlZaRE1XaXhYRVBkRTBEMVFkT1JIRXNSS1RscmplUXlERU83ZlNQS0ZwZ1A3MU5TTnJCCkFHM2NFSU45aHNQVDhOVmllZmdWem5QTkVMenFkVmdEbFhpb2VpUnV6OERKWFgvblpmU1JWKytwbk9ySTRibG4KS0twelJlNW14OTc1SjhxZ1FvRktKT0NNRlpHdkJMR2MxSzZZaEIzOHJFODZCZzgzbUovWjBEYkVmQjBxZm13cgo2ZDVFUXFsd0E5Y3JZT1YyV1VpWXprSnBLNmJZNzRZNmM1TmpBcEFKeGNiaTFOaDlRVEhUcU44N0ZtMDF0R1ZwCjVNd1pXSWZuYVRUemEvTGZLelR5U0pka0tldEZMVGdkYXpMYlpzUEE2aHBSK0FJRTJhc0tLTi84UUk1N3UzU2cKL2xyMnZKS1IvU2l5eEN1Q20vQWJkYnJMbXk0WjlSdm1jMGdpclA4T0lLQWxBRWZ2TzV5Z2hSKy8vd1RpTFlzUQp1SllDM0V2UE16ZGdKUzdGR2FscnFLZzlPTCsxVzROY05yNWdveVdSUUJ0cktKaWlTZEJVWmVxb0RvSUY5NHpCCndGbzJJT1JFdXFqcU51M3diMWZIM3p1dGdtalFra3IxVjJhd3hmcExLWlROQWdNQkFBRT0KLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg"}
+{"timestamp":1748805628,"signature":"esi8seGvz4WL/MUCeUCPGG8QqQufu04yioXdYmxMvFiMjQ40jWjwr4icQ2LOYSEqRvhdy9kXIOySwehOKi/G6L/IlqD95dthLTkfHBsAUQNuikKYwhsp8yfCjZtcZQXYX/bKxDrjCtgkqeJNFbx6BUMH53JSrcURCIkFqpq6zurkrRuLPsoktaga+JFFLzuaypNPtDE0p7/S9PmNALLSltwteBhVPTuazK2TKqZ2kll8qD2b8EGtkk0hgszFSUMlSuZ6Lq8XK5ZZsV5Wvk7sKgC6b+QXUgWOqcBYoHlq7BGWClqkgmVgvY8kax/gPNXjyzPBvCG9IWTnkV4LYBPRmKgBU25lLjSZOzSdZu0x42xi0+aBVAh9gLE10k8IlfMAImIkVeDZ/zR2AhbZS+MpLhisxtReecqKZzXjbpWFwQdjyAZdLkN6Ao7XVfRrj+TefKUPlJvwJAeKzTRhtpLvZCm893Hll49NXtOJtj7sYQYckhGvE3GCiJx/l05LCYN9","publicKey":"LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQm9qQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FZOEFNSUlCaWdLQ0FZRUFzdUhXYUhsZ0I1cVF4ZEJjTlJKSAordHR4SmoxcVY1NTdvMlZaRE1XaXhYRVBkRTBEMVFkT1JIRXNSS1RscmplUXlERU83ZlNQS0ZwZ1A3MU5TTnJCCkFHM2NFSU45aHNQVDhOVmllZmdWem5QTkVMenFkVmdEbFhpb2VpUnV6OERKWFgvblpmU1JWKytwbk9ySTRibG4KS0twelJlNW14OTc1SjhxZ1FvRktKT0NNRlpHdkJMR2MxSzZZaEIzOHJFODZCZzgzbUovWjBEYkVmQjBxZm13cgo2ZDVFUXFsd0E5Y3JZT1YyV1VpWXprSnBLNmJZNzRZNmM1TmpBcEFKeGNiaTFOaDlRVEhUcU44N0ZtMDF0R1ZwCjVNd1pXSWZuYVRUemEvTGZLelR5U0pka0tldEZMVGdkYXpMYlpzUEE2aHBSK0FJRTJhc0tLTi84UUk1N3UzU2cKL2xyMnZKS1IvU2l5eEN1Q20vQWJkYnJMbXk0WjlSdm1jMGdpclA4T0lLQWxBRWZ2TzV5Z2hSKy8vd1RpTFlzUQp1SllDM0V2UE16ZGdKUzdGR2FscnFLZzlPTCsxVzROY05yNWdveVdSUUJ0cktKaWlTZEJVWmVxb0RvSUY5NHpCCndGbzJJT1JFdXFqcU51M3diMWZIM3p1dGdtalFra3IxVjJhd3hmcExLWlROQWdNQkFBRT0KLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg"}

CHANGELOG.md

@@ -1,23 +1,51 @@
 ---
 uid: changelog
 ---
-## [1.5.1] - 2025-05-06
+
+## [1.6.1] - 2025-05-28
 
 ### Added
 
+* Two new entity command buffer systems that run at the beginning and end of the `PredictedSimulationSystemGroup` respectively: `BeginPredictedSimulationCommandBufferSystem` and `EndPredictedSimulationCommandBufferSystem`.
+* A new internal `PredictedSpawningSystemGroup`, running after the `EndPredictedSimulationCommandBufferSystem`, created to guarantee that when a new snapshot is received from server, all new ghosts are spawned and ready to receive new data.
+* New documentation regarding the NetworkDriverStore architecture, setup and how to use it in conjunction with Unity.Relay.
 * 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.
+* The ability to define a smaller `GhostSystemConstants.SnapshotHistorySize` value via compiler define `NETCODE_SNAPSHOT_HISTORY_SIZE_6` or `NETCODE_SNAPSHOT_HISTORY_SIZE_16`. These values are well suited for larger scale use-cases where server memory is constrained, and snapshot sends of individual ghosts are relatively infrequent.
+* Support for combining Ghost Relevancy with Ghost Importance Scaling via new `PrioChunks.isRelevant` field, [enabling a fast-path for relevancy calculations](https://docs.unity3d.com/Packages/com.unity.netcode@latest?subfolder=/manual/optimizations.html#relevancy-fast-path-via-importance-scaling).
+* Analytics to netcode tools to better understand their usage.
 
 ### Changed
 
+* **Behaviour Breaking Change:** Predicted spawned ghosts for partial ticks skip restoring the state from the backup (and instead continue prediction from their spawn state) when the last backup state tick is identical to the spawn tick, as no data has changed.
+* **Behaviour Breaking Change:** Reduced the complexity (and performance overhead) of the `GhostCount.GhostCountOnServer` calculations internally. Note that this value is (and always has been) an approximation.
 * IsReconnected split into NetworkStreamIsReconnected for reconnected connections and IsMigrated for re-spawned ghosts (Host Migration).
+* Moved host migration related types into a `Unity.Netcode.HostMigration` namespace, renamed the `HostMigration` class to `HostMigrationUtility` so it works in the new namespace.
+* Prespawn ghost IDs will now be preserved between host migrations
+* Client connection `NetworkIDs` are now preserved between host migrations.
 
 ### Fixed
 
+* **Behaviour Breaking Change:** Incorrect state serialized inside the `SnapshotDataBuffer` for predicted spawned ghost on the client when spawned inside the prediction loop. The `PredictedGhostSpawnSystem` is now updated also as part of the prediction loop (inside the `PredictedSpawningSystemGroup`) to ensure that any predicted spawned ghosts on the client are correctly initialized at the tick they are spawned, and not with partial tick state.
+* Issue where predicted spawned ghosts re-simulated from the wrong tick when configured to rollback to their `spawnTick` and are spawned inside the prediction loop. They are now restored using the corrected full tick state, rather than the erroneous partial tick state.
+* Enable creating and initializing server drivers when using WebGL to enable self-hosting cases using relay. Many methods were under conditional compilation flags and removed from the WebGL build and not usable outside the editor.
+* All the unmanaged systems present in the FixedStepSimulationSystemGroup that have a direct or indirect update dependency to the PhysicsSystemGroup are now correctly moved to the PredictedFixedStepSimulationSystemGroup. This is a **Behaviour Change** in respect the previous versions, where all the unmanaged systems continued to stay inside the fixed update group, regardless of the dependency of update order.
 * 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.
+* The prediction loop will no longer rollback too many times when one ghost is switched from predicted to interpolated, and later switched back to predicted, when that ghost is the only predicted ghost.
+* If you update multiple packages, create a new section with a new header for the other package.
+* The client packet dump was not being written to the `EnablePacketLogging.NetDebugPacketCache` field, thus were not usable by users and other netcode call-sites (like the `NetworkStreamReceiveSystem`).
+* `SnapshotHistorySize` values below 32 uncovered an issue where a ghost chunk being written would write over its snapshot history entries for currently-in-flight snapshots, leading to a cycle of never being able to fetch a valid baseline, in perpetuity. The fix for this requires us to stall the send of this ghost chunk if the in-flight queue is full, until the in-flight snapshots are assumed to have either arrived or been lost/dropped.
+* Buffer serialization errors caused by incorrect pointer stepping when ghost fields are not present (i.e. surrounding `GhostComponentSerializer.State.HasGhostFields`).
+* Buffer serialization errors caused by missing change mask invalidation when `SendToOwnerType` or `GhostSendType` conditionally prevented sending of the buffer.
+* Readded `UsePreSerialization` to the `GhostAuthoringComponent` inspector that was accidentally removed.
+
+### Obsolete
+
+* Prefer `BatchScaleImportanceDelegate` to `ScaleImportanceFunction` as the latter significantly reduces the total number of function pointer calls.
+
 
 
 ## [1.5.0] - 2025-04-22
@@ -74,7 +102,7 @@ uid: changelog
 * Inconsistencies in documentation around RollbackPredictionOnStructuralChanges have been fixed and sorted out a couple of typos.
 * Issue with prespawned ghosts not updating anymore after the client disconnects and reconnects to a server.
 * Issue where Ghost Importance Scaling would throw if the `GhostDistancePartitionShared` (or user-code equivalent `GhostImportancePerChunkDataType`) was only added to a subset of ghost instances.
-* The `GhostDistancePartitioningSystem` is now significantly faster in cases where the `GhostDistancePartitionShared` is able to successfully exclude unchanged `LocalTransform` chunks (via change filtering). `AddSharedDistancePartitionJob` is now `.ScheduleParallel` (from `.Schedule`), as there is no reason not to queue ECB operations in parallel.
+* The `GhostDistancePartitioningSystem` is now significantly faster in cases where the `GhostDistancePartitionShared` is able to successfully exclude unchanged `LocalTransform` chunks (via change filtering).
 * an issue in MultiPhysics sample, causing particle emitter not spawning particles in the client-only physics world.
 * an issues with GhostPresentationGameObjectSystem throwing ObjectDisposedExceptions when entity are destroyed.
 * an issues with GhostPresentationGameObjectSystem throwing exceptions trying accessing ComponentLookup after structural changes.
@@ -93,11 +121,10 @@ uid: changelog
 * an issue when using custom templates for type that handle different smoothing options. This was failing validation and causing compilation error, even when it was not the case.
 * Case where `GhostUpdateSystem.RestorePredictionBackup` would cause change version changes on unchanged child components (as `PredictionBackupJob` was not updating the `childChangeVersions` pointer when `HasGhostFields == 0 && SerializesEnabledBit != 0`).
 * "Size limitation on snapshot did not prevent all errors" and improper serialization of a ghost group root when the group is empty and the available space in the data stream is not enough to encode the length of the group (0, that takes 2 bits).
-* missing reset of the entity sent state when a group fail to serialize. The serialized children entity were incorrectly reported to be sent, potentially causing improper baseline used by the server to delta compress the data.
-* incorrect warning message when run in background is disable.
+* Missing reset of the entity sent state when a group fail to serialize. The serialized children entity were incorrectly reported to be sent, potentially causing improper baseline used by the server to delta compress the data.
+* Incorrect warning message when run in background is disable.
 * Esoteric `IBufferElementData` serialization issue caused by an incorrect assumption that `stackalloc` would default init its elements.
 
-
 ## [1.4.0] - 2024-11-14
 
 ### Added

Documentation~/TableOfContents.md

@@ -3,6 +3,8 @@
 * [Setting up client and server worlds](set-up-client-server-worlds.md)
   * [Client and server worlds networking model](client-server-worlds.md)
   * [Network protocol checks](network-protocol-checks.md)
+  * [Netcode for Entities multi-driver architecture](networking-network-drivers.md)
+  * [Use Unity Relay with Netcode for Entities](networking-using-relay.md)
 * [Creating multiplayer gameplay](creating-multiplayer-gameplay.md)
   * [Connecting server and clients](network-connection.md)
   * [Synchronizing states and inputs](synchronization.md)

Documentation~/filter.yml

@@ -23,9 +23,6 @@ apiRules:
   - exclude:
       uidRegex: \.OnInspectorGUI$
       type: Method
-  - exclude:
-      uidRegex: .*Tests.*
-      type: Namespace
   - exclude:
       uidRegex: \.__COMMAND_NAMESPACE__$
       type: Namespace
@@ -38,4 +35,21 @@ apiRules:
   - exclude:
       uidRegex: \.ToString$
       type: Method
-
+  - exclude:
+      uidRegex: ^Unity\.NetCode\.Tests\.FixedListComplexData.*$
+      type: Struct
+  - exclude:
+      uidRegex: ^Unity\.NetCode\.Tests\.HybridComponentWeWillOverride$
+      type: Class
+  - exclude:
+      uidRegex: ^Unity\.NetCode\.Tests\.SimpleData.*$
+      type: Struct
+  - exclude:
+      uidRegex: ^Unity\.NetCode\.Tests\.FixedElement8.*$
+      type: Struct
+  - exclude:
+      uidRegex: ^Unity\.NetCode\.Tests\.Nested.*$
+      type: Struct
+  - exclude:
+      uidRegex: ^Unity\.NetCode\.Tests\.(.*)(Variant|Variation).*$
+      type: Struct

Documentation~/ghost-snapshots.md

@@ -45,6 +45,68 @@ E.g. `NetworkTickRate:30Hz`, `MaxSendRate:45` means 30Hz is the actual maximum s
 * __Dynamic__: The ghost is optimized for a small snapshot size when both changing and not changing.
 * __Static__: The ghost isn't optimized for a small snapshot size when changing, but isn't sent at all when it's not changing.
 
+## Structural changes on instantiated ghosts
+
+You can make some structural changes to already instantiated ghost prefabs, such as [adding or removing components](#add-or-remove-components-on-an-instantiated-prefab) or [adding, removing, or destroying child entities](#add-remove-or-destroy-child-entities-on-an-instantiated-prefab), although there are limitations.
+
+| Action                                         | Supported  | Limitations                                                                |
+|------------------------------------------------|------------|----------------------------------------------------------------------------|
+| Add or remove components or buffers            | Yes        | None                                                                       |                                                  |
+| Add or remove replicated components or buffers | Yes        | Refer to [adding or removing components](#add-or-remove-components-on-an-instantiated-prefab)                        |
+| Add, remove, or destroy child entities                   | Yes        | Refer to [adding, removing, or destroying child entities](#add-remove-or-destroy-child-entities-on-an-instantiated-prefab)   |
+
+> [!NOTE]
+> Adding, removing, or destroying child entities is not technically a structural change, but has implications for replication.
+
+### Add or remove components on an instantiated prefab
+
+You can add or remove any user-side components from both the root and child entities of an instantiated prefab and serialization and deserialization of the ghost, as well as delta compression, will continue to work.
+
+However, adding a component to an instantiated ghost (even if it has a `[GhostField]`), will not replicate the component to other instances of the same ghost prefab. For a component to be replicated, it must be part of the prefab at authoring time.
+
+### Add, remove, or destroy child entities on an instantiated prefab
+
+You can't remove or change the index of any replicated child entity within the `LinkedEntityGroup` buffer, since doing so can cause serialization and deserialization errors. You can, however, do the following:
+
+* Destroy any child entity in the `LinkedEntityGroup`, with or without replicated components, as long as you don't re-order or remove the associated entry in the `LinkedEntityGroup`.
+* Remove entities from the `LinkedEntityGroup` buffer, as long as doing so doesn't cause a re-ordering of the original replicated child entities.
+* Append entities to the `LinkedEntityGroup`.
+    * In general, avoid prepending or inserting entities in between the original entries of the `LinkedEntityGroup` buffer. However, you can insert an entity in the `LinkedEntityGroup` after the last children that has replicated components.
+
+Refer to the following examples of valid and invalid configurations for more details:
+
+```
+// This is a valid configuration, where (*) denotes a destroyed entity.
+root
+  child 1 (*) <-- Replicated
+  child 2
+  child 3     <-- Replicated
+  child 4 (*)
+
+// This is a valid configuration, where entities have been appended.
+root
+  child 1   <-- Replicated
+  child 2   <-- Replicated
+  =-----=  Append / Remove after here
+  child 3
+  user entity 1
+  user entity 2
+
+// This is an invalid configuration because entities have been prepended, changing the index.
+root
+  new user entity 1 <--- INVALID, break replicated entity indexes
+  child 1  <-- Replicated
+  child 2  <-- Replicated
+  child 3
+
+// This is an invalid configuration, because entities have been added in between original entries, changing the index.
+root
+  child 1  <-- Replicated
+  new user entity 1 <--- INVALID, break replicated entity indexes
+  child 2  <-- Replicated
+  child 3
+```
+
 ## Synchronize ghost components and fields
 
 Netcode for Entities uses C# attributes to configure which components and fields to synchronize as part of a ghost.