com.unity.netcode.gameobjects@2.2.0

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

Additional documentation and release notes are available at [Multiplayer Documentation](https://docs-multiplayer.unity3d.com).

## [2.2.0] - 2024-12-12

### Added

- Added `NetworkObject.OwnershipStatus.SessionOwner` to allow Network Objects to be distributable and only owned by the Session Owner. This flag will override all other `OwnershipStatus` flags. (#3175)
- Added `UnityTransport.GetEndpoint` method to provide a way to obtain `NetworkEndpoint` information of a connection via client identifier. (#3130)
- Added `NetworkTransport.OnEarlyUpdate` and `NetworkTransport.OnPostLateUpdate` methods to provide more control over handling transport related events at the start and end of each frame. (#3113)

### Fixed

- Fixed issue where the server, host, or session owner would not populate the in-scene place `NetworkObject` table if the scene was loaded prior to starting the `NetworkManager`. (#3177)
- Fixed issue where the `NetworkObjectIdHash` value could be incorrect when entering play mode while still in prefab edit mode with pending changes and using MPPM. (#3162)
- Fixed issue where a sever only `NetworkManager` instance would spawn the actual `NetworkPrefab`'s `GameObject` as opposed to creating an instance of it. (#3160)
- Fixed issue where only the session owner (as opposed to all clients) would handle spawning prefab overrides properly when using a distributed authority network topology. (#3160)
- Fixed issue where an exception was thrown when calling `NetworkManager.Shutdown` after calling `UnityTransport.Shutdown`. (#3118)
- Fixed issue where `NetworkList` properties on in-scene placed `NetworkObject`s could cause small memory leaks when entering playmode. (#3147)
- Fixed in-scene `NertworkObject` synchronization issue when loading a scene with currently connected clients connected to a session created by a `NetworkManager` started as a server (i.e. not as a host). (#3133)
- Fixed issue where a `NetworkManager` started as a server would not add itself as an observer to in-scene placed `NetworkObject`s instantiated and spawned by a scene loading event. (#3133)
- Fixed issue where spawning a player using `NetworkObject.InstantiateAndSpawn` or `NetworkSpawnManager.InstantiateAndSpawn` would not update the `NetworkSpawnManager.PlayerObjects` or assign the newly spawned player to the `NetworkClient.PlayerObject`. (#3122)
- Fixed issue where queued UnitTransport (NetworkTransport) message batches were being sent on the next frame. They are now sent at the end of the frame during `PostLateUpdate`.  (#3113)
- Fixed issue where `NotOwnerRpcTarget` or `OwnerRpcTarget` were not using their replacements `NotAuthorityRpcTarget` and `AuthorityRpcTarget` which would invoke a warning. (#3111)
- Fixed issue where client is removed as an observer from spawned objects when their player instance is despawned. (#3110)
- Fixed issue where `NetworkAnimator` would statically allocate write buffer space for `Animator` parameters that could cause a write error if the number of parameters exceeded the space allocated. (#3108)

### Changed

- In-scene placed `NetworkObject`s have been made distributable when balancing object distribution after a connection event. (#3175)
- Optimised `NetworkVariable` and `NetworkTransform` related packets when in Distributed Authority mode.
- The Debug Simulator section of the Unity Transport component was removed. This section was not functional anymore and users are now recommended to use the more featureful [Network Simulator](https://docs-multiplayer.unity3d.com/tools/current/tools-network-simulator/) tool from the Multiplayer Tools package instead. (#3121)

Tests/Runtime/Prefabs/AddNetworkPrefabTests.cs

@@ -0,0 +1,141 @@
+using System.Collections;
+using NUnit.Framework;
+using Unity.Netcode.TestHelpers.Runtime;
+using UnityEngine;
+using UnityEngine.TestTools;
+using Object = UnityEngine.Object;
+
+namespace Unity.Netcode.RuntimeTests
+{
+    internal class AddNetworkPrefabTest : NetcodeIntegrationTest
+    {
+        internal class EmptyComponent : NetworkBehaviour
+        {
+
+        }
+        protected override int NumberOfClients => 1;
+
+        private GameObject m_Prefab;
+
+        protected override IEnumerator OnSetup()
+        {
+            // Host is irrelevant, messages don't get sent to the host "client"
+            m_UseHost = false;
+
+            yield return null;
+        }
+
+        protected override void OnServerAndClientsCreated()
+        {
+            m_Prefab = new GameObject("Object");
+            var networkObject = m_Prefab.AddComponent<NetworkObject>();
+            m_Prefab.AddComponent<EmptyComponent>();
+
+            // Make it a prefab
+            NetcodeIntegrationTestHelpers.MakeNetworkObjectTestPrefab(networkObject);
+
+            m_ServerNetworkManager.NetworkConfig.SpawnTimeout = 0;
+            m_ServerNetworkManager.NetworkConfig.ForceSamePrefabs = false;
+            foreach (var client in m_ClientNetworkManagers)
+            {
+                client.NetworkConfig.SpawnTimeout = 0;
+                client.NetworkConfig.ForceSamePrefabs = false;
+            }
+        }
+
+        private EmptyComponent GetObjectForClient(ulong clientId)
+        {
+#if UNITY_2023_1_OR_NEWER
+            var emptyComponents = Object.FindObjectsByType<EmptyComponent>(FindObjectsSortMode.InstanceID);
+#else
+            var emptyComponents = Object.FindObjectsOfType<EmptyComponent>();
+#endif
+            foreach (var component in emptyComponents)
+            {
+                if (component.IsSpawned && component.NetworkManager.LocalClientId == clientId)
+                {
+                    return component;
+                }
+            }
+            return null;
+        }
+
+        private void RegisterPrefab()
+        {
+            m_ServerNetworkManager.AddNetworkPrefab(m_Prefab);
+            foreach (var client in m_ClientNetworkManagers)
+            {
+                client.AddNetworkPrefab(m_Prefab);
+            }
+        }
+
+        private void DeregisterPrefab()
+        {
+            m_ServerNetworkManager.RemoveNetworkPrefab(m_Prefab);
+            foreach (var client in m_ClientNetworkManagers)
+            {
+                client.RemoveNetworkPrefab(m_Prefab);
+            }
+        }
+
+        private static CoroutineRunner s_CoroutineRunner;
+
+        [UnityTest]
+        public IEnumerator WhenSpawningBeforeAddingPrefab_SpawnFails()
+        {
+            var serverObject = Object.Instantiate(m_Prefab);
+            serverObject.GetComponent<NetworkObject>().NetworkManagerOwner = m_ServerNetworkManager;
+            serverObject.GetComponent<NetworkObject>().Spawn();
+            yield return NetcodeIntegrationTestHelpers.WaitForMessageOfTypeReceived<CreateObjectMessage>(m_ClientNetworkManagers[0]);
+            Assert.IsNull(GetObjectForClient(m_ClientNetworkManagers[0].LocalClientId));
+        }
+
+        [UnityTest]
+        public IEnumerator WhenSpawningAfterAddingServerPrefabButBeforeAddingClientPrefab_SpawnFails()
+        {
+            m_ServerNetworkManager.AddNetworkPrefab(m_Prefab);
+
+            var serverObject = Object.Instantiate(m_Prefab);
+            serverObject.GetComponent<NetworkObject>().NetworkManagerOwner = m_ServerNetworkManager;
+            serverObject.GetComponent<NetworkObject>().Spawn();
+            yield return NetcodeIntegrationTestHelpers.WaitForMessageOfTypeReceived<CreateObjectMessage>(m_ClientNetworkManagers[0]);
+            Assert.IsNull(GetObjectForClient(m_ClientNetworkManagers[0].LocalClientId));
+        }
+
+        [UnityTest]
+        public IEnumerator WhenSpawningAfterAddingPrefabOnServerAndClient_SpawnSucceeds()
+        {
+            RegisterPrefab();
+
+            var serverObject = Object.Instantiate(m_Prefab);
+            serverObject.GetComponent<NetworkObject>().NetworkManagerOwner = m_ServerNetworkManager;
+            serverObject.GetComponent<NetworkObject>().Spawn();
+            yield return NetcodeIntegrationTestHelpers.WaitForMessageOfTypeHandled<CreateObjectMessage>(m_ClientNetworkManagers[0]);
+            Assert.IsNotNull(GetObjectForClient(m_ClientNetworkManagers[0].LocalClientId));
+        }
+
+        [UnityTest]
+        public IEnumerator WhenSpawningAfterRemovingPrefabOnClient_SpawnFails()
+        {
+            RegisterPrefab();
+
+            var serverObject = Object.Instantiate(m_Prefab);
+            serverObject.GetComponent<NetworkObject>().NetworkManagerOwner = m_ServerNetworkManager;
+            serverObject.GetComponent<NetworkObject>().Spawn();
+            yield return NetcodeIntegrationTestHelpers.WaitForMessageOfTypeReceived<CreateObjectMessage>(m_ClientNetworkManagers[0]);
+            Assert.IsNotNull(GetObjectForClient(m_ClientNetworkManagers[0].LocalClientId));
+
+            serverObject.GetComponent<NetworkObject>().Despawn();
+            yield return NetcodeIntegrationTestHelpers.WaitForMessageOfTypeReceived<DestroyObjectMessage>(m_ClientNetworkManagers[0]);
+            Assert.IsNull(GetObjectForClient(m_ClientNetworkManagers[0].LocalClientId));
+
+            DeregisterPrefab();
+
+            serverObject = Object.Instantiate(m_Prefab);
+            serverObject.GetComponent<NetworkObject>().NetworkManagerOwner = m_ServerNetworkManager;
+            serverObject.GetComponent<NetworkObject>().Spawn();
+            yield return NetcodeIntegrationTestHelpers.WaitForMessageOfTypeReceived<CreateObjectMessage>(m_ClientNetworkManagers[0]);
+            Assert.IsNull(GetObjectForClient(m_ClientNetworkManagers[0].LocalClientId));
+        }
+    }
+}

Tests/Runtime/Prefabs/AddNetworkPrefabTests.cs.meta

@@ -0,0 +1,3 @@
+fileFormatVersion: 2
+guid: 67012fa25fe64aeda8fbf60340c1bc2f
+timeCreated: 1652205947

Tests/Runtime/Prefabs/NetworkPrefabHandlerTests.cs

@@ -0,0 +1,245 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using NUnit.Framework;
+using Unity.Netcode.TestHelpers.Runtime;
+using UnityEngine;
+
+namespace Unity.Netcode.RuntimeTests
+{
+    /// <summary>
+    /// The NetworkPrefabHandler unit tests validates:
+    /// Registering with GameObject, NetworkObject, or GlobalObjectIdHash
+    /// Newly assigned rotation or position values for newly spawned NetworkObject instances are valid
+    /// Destroying a newly spawned NetworkObject instance works
+    /// Removing a INetworkPrefabInstanceHandler is removed and can be verified (very last check)
+    /// </summary>
+    internal class NetworkPrefabHandlerTests
+    {
+
+        private const string k_TestPrefabObjectName = "NetworkPrefabTestObject";
+        private uint m_ObjectId = 1;
+        private GameObject MakeValidNetworkPrefab()
+        {
+            Guid baseObjectID = NetworkManagerHelper.AddGameNetworkObject(k_TestPrefabObjectName + m_ObjectId.ToString());
+            NetworkObject validPrefab = NetworkManagerHelper.InstantiatedNetworkObjects[baseObjectID];
+            NetcodeIntegrationTestHelpers.MakeNetworkObjectTestPrefab(validPrefab);
+            m_ObjectId++;
+            return validPrefab.gameObject;
+        }
+
+        /// <summary>
+        /// Tests the NetwokConfig NetworkPrefabsList initialization during NetworkManager's Init method to make sure that
+        /// it will still initialize but remove the invalid prefabs
+        /// </summary>
+        [Test]
+        public void NetworkConfigInvalidNetworkPrefabTest()
+        {
+
+            // Add null entry
+            NetworkManagerHelper.NetworkManagerObject.NetworkConfig.Prefabs.Add(null);
+
+            // Add a NetworkPrefab with no prefab
+            NetworkManagerHelper.NetworkManagerObject.NetworkConfig.Prefabs.Add(new NetworkPrefab());
+
+            // Add a NetworkPrefab override with an invalid hash
+            NetworkManagerHelper.NetworkManagerObject.NetworkConfig.Prefabs.Add(new NetworkPrefab() { Override = NetworkPrefabOverride.Hash, SourceHashToOverride = 0 });
+
+            // Add a NetworkPrefab override with a valid hash but an invalid target prefab
+            NetworkManagerHelper.NetworkManagerObject.NetworkConfig.Prefabs.Add(new NetworkPrefab() { Override = NetworkPrefabOverride.Hash, SourceHashToOverride = 654321, OverridingTargetPrefab = null });
+
+            // Add a NetworkPrefab override with a valid hash to override but an invalid target prefab
+            NetworkManagerHelper.NetworkManagerObject.NetworkConfig.Prefabs.Add(new NetworkPrefab() { Override = NetworkPrefabOverride.Prefab, SourceHashToOverride = 654321, OverridingTargetPrefab = null });
+
+            // Add a NetworkPrefab override with an invalid source prefab to override
+            NetworkManagerHelper.NetworkManagerObject.NetworkConfig.Prefabs.Add(new NetworkPrefab() { Override = NetworkPrefabOverride.Prefab, SourcePrefabToOverride = null });
+
+            // Add a NetworkPrefab override with a valid source prefab to override but an invalid target prefab
+            NetworkManagerHelper.NetworkManagerObject.NetworkConfig.Prefabs.Add(new NetworkPrefab() { Override = NetworkPrefabOverride.Prefab, SourcePrefabToOverride = MakeValidNetworkPrefab(), OverridingTargetPrefab = null });
+
+            // Add a valid prefab
+            NetworkManagerHelper.NetworkManagerObject.NetworkConfig.Prefabs.Add(new NetworkPrefab() { Prefab = MakeValidNetworkPrefab() });
+
+            // Add a NetworkPrefab override with a valid hash and valid target prefab
+            NetworkManagerHelper.NetworkManagerObject.NetworkConfig.Prefabs.Add(new NetworkPrefab() { Override = NetworkPrefabOverride.Hash, SourceHashToOverride = 11111111, OverridingTargetPrefab = MakeValidNetworkPrefab() });
+
+            // Add a NetworkPrefab override with a valid prefab and valid target prefab
+            NetworkManagerHelper.NetworkManagerObject.NetworkConfig.Prefabs.Add(new NetworkPrefab() { Override = NetworkPrefabOverride.Prefab, SourcePrefabToOverride = MakeValidNetworkPrefab(), OverridingTargetPrefab = MakeValidNetworkPrefab() });
+
+            var exceptionOccurred = false;
+            try
+            {
+                NetworkManagerHelper.NetworkManagerObject.StartHost();
+            }
+            catch
+            {
+                exceptionOccurred = true;
+            }
+
+            Assert.False(exceptionOccurred);
+
+            // In the end we should only have 3 valid registered network prefabs
+            Assert.True(NetworkManagerHelper.NetworkManagerObject.NetworkConfig.Prefabs.NetworkPrefabOverrideLinks.Count == 3);
+        }
+
+        private const string k_PrefabObjectName = "NetworkPrefabHandlerTestObject";
+
+        [Test]
+        public void NetworkPrefabHandlerClass([Values] bool distributedAuthority)
+        {
+            var networkConfig = new NetworkConfig()
+            {
+                NetworkTopology = distributedAuthority ? NetworkTopologyTypes.DistributedAuthority : NetworkTopologyTypes.ClientServer,
+            };
+
+            Assert.IsTrue(NetworkManagerHelper.StartNetworkManager(out _, networkConfig: networkConfig));
+            var testPrefabObjectName = k_PrefabObjectName;
+
+            Guid baseObjectID = NetworkManagerHelper.AddGameNetworkObject(testPrefabObjectName);
+            NetworkObject baseObject = NetworkManagerHelper.InstantiatedNetworkObjects[baseObjectID];
+
+            var networkPrefabHandler = new NetworkPrefabHandler();
+            var networkPrefaInstanceHandler = new NetworkPrefaInstanceHandler(baseObject);
+
+            var prefabPosition = new Vector3(1.0f, 5.0f, 3.0f);
+            var prefabRotation = new Quaternion(1.0f, 0.5f, 0.4f, 0.1f);
+
+            //Register via GameObject
+            var gameObjectRegistered = networkPrefabHandler.AddHandler(baseObject.gameObject, networkPrefaInstanceHandler);
+
+            //Test result of registering via GameObject reference
+            Assert.True(gameObjectRegistered);
+
+            var spawnedObject = networkPrefabHandler.HandleNetworkPrefabSpawn(baseObject.GlobalObjectIdHash, 0, prefabPosition, prefabRotation);
+
+            //Test that something was instantiated
+            Assert.NotNull(spawnedObject);
+
+            //Test that this is indeed an instance of our original object
+            Assert.True(spawnedObject.name.Contains(testPrefabObjectName));
+
+            //Test for position and rotation
+            Assert.True(prefabPosition == spawnedObject.transform.position);
+            Assert.True(prefabRotation == spawnedObject.transform.rotation);
+
+            networkPrefabHandler.HandleNetworkPrefabDestroy(spawnedObject);     //Destroy our prefab instance
+            networkPrefabHandler.RemoveHandler(baseObject);                     //Remove our handler
+
+            //Register via NetworkObject
+            gameObjectRegistered = networkPrefabHandler.AddHandler(baseObject, networkPrefaInstanceHandler);
+
+            //Test result of registering via NetworkObject reference
+            Assert.True(gameObjectRegistered);
+
+            //Change it up
+            prefabPosition = new Vector3(2.0f, 1.0f, 5.0f);
+            prefabRotation = new Quaternion(4.0f, 1.5f, 5.4f, 5.1f);
+
+            spawnedObject = networkPrefabHandler.HandleNetworkPrefabSpawn(baseObject.GlobalObjectIdHash, 0, prefabPosition, prefabRotation);
+
+            //Test that something was instantiated
+            Assert.NotNull(spawnedObject);
+
+            //Test that this is indeed an instance of our original object
+            Assert.True(spawnedObject.name.Contains(testPrefabObjectName));
+
+            //Test for position and rotation
+            Assert.True(prefabPosition == spawnedObject.transform.position);
+            Assert.True(prefabRotation == spawnedObject.transform.rotation);
+
+            networkPrefabHandler.HandleNetworkPrefabDestroy(spawnedObject);     //Destroy our prefab instance
+            networkPrefabHandler.RemoveHandler(baseObject);                     //Remove our handler
+
+            //Register via GlobalObjectIdHash
+            gameObjectRegistered = networkPrefabHandler.AddHandler(baseObject.GlobalObjectIdHash, networkPrefaInstanceHandler);
+
+            //Test result of registering via GlobalObjectIdHash reference
+            Assert.True(gameObjectRegistered);
+
+            //Change it up
+            prefabPosition = new Vector3(6.0f, 4.0f, 1.0f);
+            prefabRotation = new Quaternion(3f, 2f, 4f, 1f);
+
+            spawnedObject = networkPrefabHandler.HandleNetworkPrefabSpawn(baseObject.GlobalObjectIdHash, 0, prefabPosition, prefabRotation);
+
+            //Test that something was instantiated
+            Assert.NotNull(spawnedObject);
+
+            //Test that this is indeed an instance of our original object
+            Assert.True(spawnedObject.name.Contains(testPrefabObjectName));
+
+            //Test for position and rotation
+            Assert.True(prefabPosition == spawnedObject.transform.position);
+            Assert.True(prefabRotation == spawnedObject.transform.rotation);
+
+            networkPrefabHandler.HandleNetworkPrefabDestroy(spawnedObject);     //Destroy our prefab instance
+            networkPrefabHandler.RemoveHandler(baseObject);                     //Remove our handler
+
+            Assert.False(networkPrefaInstanceHandler.StillHasInstances());
+        }
+
+        [SetUp]
+        public void Setup()
+        {
+            //Create, instantiate, and host
+            NetworkManagerHelper.StartNetworkManager(out _, NetworkManagerHelper.NetworkManagerOperatingMode.None);
+        }
+
+        [TearDown]
+        public void TearDown()
+        {
+            //Stop, shutdown, and destroy
+            NetworkManagerHelper.ShutdownNetworkManager();
+
+#if UNITY_2023_1_OR_NEWER
+            var networkObjects = UnityEngine.Object.FindObjectsByType<NetworkObject>(FindObjectsSortMode.InstanceID).ToList();
+#else
+            var networkObjects = UnityEngine.Object.FindObjectsOfType<NetworkObject>().ToList();
+#endif
+
+            var networkObjectsList = networkObjects.Where(c => c.name.Contains(k_PrefabObjectName));
+            foreach (var networkObject in networkObjectsList)
+            {
+                UnityEngine.Object.DestroyImmediate(networkObject);
+            }
+        }
+    }
+
+    /// <summary>
+    /// The Prefab instance handler to use for this test
+    /// </summary>
+    internal class NetworkPrefaInstanceHandler : INetworkPrefabInstanceHandler
+    {
+        private NetworkObject m_NetworkObject;
+
+        private List<NetworkObject> m_Instances;
+
+        public NetworkObject Instantiate(ulong ownerClientId, Vector3 position, Quaternion rotation)
+        {
+            var networkObjectInstance = UnityEngine.Object.Instantiate(m_NetworkObject.gameObject).GetComponent<NetworkObject>();
+            networkObjectInstance.transform.position = position;
+            networkObjectInstance.transform.rotation = rotation;
+            m_Instances.Add(networkObjectInstance);
+            return networkObjectInstance;
+        }
+
+        public void Destroy(NetworkObject networkObject)
+        {
+            var instancesContainsNetworkObject = m_Instances.Contains(networkObject);
+            Assert.True(instancesContainsNetworkObject);
+            m_Instances.Remove(networkObject);
+            UnityEngine.Object.Destroy(networkObject.gameObject);
+        }
+
+        public bool StillHasInstances()
+        {
+            return (m_Instances.Count > 0);
+        }
+
+        public NetworkPrefaInstanceHandler(NetworkObject networkObject)
+        {
+            m_NetworkObject = networkObject;
+            m_Instances = new List<NetworkObject>();
+        }
+    }
+}

Tests/Runtime/Prefabs/NetworkPrefabHandlerTests.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 590750036c5d65c43bbc696071aa3541
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

Tests/Runtime/Prefabs/NetworkPrefabOverrideTests.cs

@@ -0,0 +1,268 @@
+using System.Collections;
+using System.Linq;
+using System.Text;
+using NUnit.Framework;
+using Unity.Netcode.TestHelpers.Runtime;
+using UnityEngine;
+using UnityEngine.TestTools;
+
+namespace Unity.Netcode.RuntimeTests
+{
+    /// <summary>
+    /// Integration test that validates spawning instances of <see cref="NetworkPrefab"/>s with overrides and
+    /// <see cref="NetworkPrefabHandler"/> registered overrides.
+    /// </summary>
+    [TestFixture(NetworkTopologyTypes.ClientServer, HostOrServer.Server)]
+    [TestFixture(NetworkTopologyTypes.ClientServer, HostOrServer.Host)]
+    [TestFixture(NetworkTopologyTypes.DistributedAuthority, HostOrServer.DAHost)]
+    internal class NetworkPrefabOverrideTests : NetcodeIntegrationTest
+    {
+        private const string k_PrefabRootName = "PrefabObj";
+        protected override int NumberOfClients => 2;
+
+        private NetworkPrefab m_ClientSidePlayerPrefab;
+        private NetworkPrefab m_PrefabOverride;
+
+        public NetworkPrefabOverrideTests(NetworkTopologyTypes networkTopologyType, HostOrServer hostOrServer) : base(networkTopologyType, hostOrServer) { }
+
+        /// <summary>
+        /// Prefab override handler that will instantiate the ServerSideInstance (m_PlayerPrefab) only on server instances
+        /// and will spawn the ClientSideInstance (m_ClientSidePlayerPrefab.Prefab) only on clients and/or a host.
+        /// </summary>
+        public class TestPrefabOverrideHandler : MonoBehaviour, INetworkPrefabInstanceHandler
+        {
+            public GameObject ServerSideInstance;
+            public GameObject ClientSideInstance;
+            private NetworkManager m_NetworkManager;
+
+            private void Start()
+            {
+                m_NetworkManager = GetComponent<NetworkManager>();
+                m_NetworkManager.PrefabHandler.AddHandler(ServerSideInstance, this);
+            }
+
+            private void OnDestroy()
+            {
+                if (m_NetworkManager != null && m_NetworkManager.PrefabHandler != null)
+                {
+                    m_NetworkManager.PrefabHandler.RemoveHandler(ServerSideInstance);
+                }
+            }
+
+            public NetworkObject Instantiate(ulong ownerClientId, Vector3 position, Quaternion rotation)
+            {
+                var instance = m_NetworkManager.IsClient ? Instantiate(ClientSideInstance) : Instantiate(ServerSideInstance);
+                return instance.GetComponent<NetworkObject>();
+            }
+
+            public void Destroy(NetworkObject networkObject)
+            {
+                Object.Destroy(networkObject);
+            }
+        }
+
+        /// <summary>
+        /// Mock component for testing that the client-side player is using the right
+        /// network prefab.
+        /// </summary>
+        public class ClientSideOnlyComponent : MonoBehaviour
+        {
+
+        }
+
+        /// <summary>
+        /// When we create the player prefab, make a modified instance that will be used
+        /// with the <see cref="TestPrefabOverrideHandler"/>.
+        /// </summary>
+        protected override void OnCreatePlayerPrefab()
+        {
+            var clientPlayer = Object.Instantiate(m_PlayerPrefab);
+            clientPlayer.AddComponent<ClientSideOnlyComponent>();
+            Object.DontDestroyOnLoad(clientPlayer);
+            m_ClientSidePlayerPrefab = new NetworkPrefab()
+            {
+                Prefab = clientPlayer,
+            };
+
+            base.OnCreatePlayerPrefab();
+        }
+
+        /// <summary>
+        /// Add the additional <see cref="NetworkPrefab"/>s and <see cref="TestPrefabOverrideHandler"/>s to
+        /// all <see cref="NetworkManager"/> instances.
+        /// </summary>
+        protected override void OnServerAndClientsCreated()
+        {
+            // Create a NetworkPrefab with an override
+            var basePrefab = NetcodeIntegrationTestHelpers.CreateNetworkObject($"{k_PrefabRootName}-base", m_ServerNetworkManager, true);
+            var targetPrefab = NetcodeIntegrationTestHelpers.CreateNetworkObject($"{k_PrefabRootName}-over", m_ServerNetworkManager, true);
+            m_PrefabOverride = new NetworkPrefab()
+            {
+                Prefab = basePrefab,
+                Override = NetworkPrefabOverride.Prefab,
+                SourcePrefabToOverride = basePrefab,
+                OverridingTargetPrefab = targetPrefab,
+            };
+
+            // Add the prefab override handler for instance specific player prefabs to the server side
+            var playerPrefabOverrideHandler = m_ServerNetworkManager.gameObject.AddComponent<TestPrefabOverrideHandler>();
+            playerPrefabOverrideHandler.ServerSideInstance = m_PlayerPrefab;
+            playerPrefabOverrideHandler.ClientSideInstance = m_ClientSidePlayerPrefab.Prefab;
+
+            // Add the NetworkPrefab with override
+            m_ServerNetworkManager.NetworkConfig.Prefabs.Add(m_PrefabOverride);
+            // Add the client player prefab that will be used on clients (and the host)
+            m_ServerNetworkManager.NetworkConfig.Prefabs.Add(m_ClientSidePlayerPrefab);
+
+            foreach (var networkManager in m_ClientNetworkManagers)
+            {
+                // Add the prefab override handler for instance specific player prefabs to the client side
+                playerPrefabOverrideHandler = networkManager.gameObject.AddComponent<TestPrefabOverrideHandler>();
+                playerPrefabOverrideHandler.ServerSideInstance = m_PlayerPrefab;
+                playerPrefabOverrideHandler.ClientSideInstance = m_ClientSidePlayerPrefab.Prefab;
+
+                // Add the NetworkPrefab with override
+                networkManager.NetworkConfig.Prefabs.Add(m_PrefabOverride);
+                // Add the client player prefab that will be used on clients (and the host)
+                networkManager.NetworkConfig.Prefabs.Add(m_ClientSidePlayerPrefab);
+            }
+
+            m_PrefabOverride.Prefab.GetComponent<NetworkObject>().IsSceneObject = false;
+            m_PrefabOverride.SourcePrefabToOverride.GetComponent<NetworkObject>().IsSceneObject = false;
+            m_PrefabOverride.OverridingTargetPrefab.GetComponent<NetworkObject>().IsSceneObject = false;
+            m_ClientSidePlayerPrefab.Prefab.GetComponent<NetworkObject>().IsSceneObject = false;
+
+            base.OnServerAndClientsCreated();
+        }
+
+        protected override IEnumerator OnTearDown()
+        {
+            if (m_PrefabOverride != null)
+            {
+                if (m_PrefabOverride.SourcePrefabToOverride)
+                {
+                    Object.Destroy(m_PrefabOverride.SourcePrefabToOverride);
+                }
+
+                if (m_PrefabOverride.OverridingTargetPrefab)
+                {
+                    Object.Destroy(m_PrefabOverride.OverridingTargetPrefab);
+                }
+            }
+
+            if (m_ClientSidePlayerPrefab != null)
+            {
+                if (m_ClientSidePlayerPrefab.Prefab)
+                {
+                    Object.Destroy(m_ClientSidePlayerPrefab.Prefab);
+                }
+            }
+            m_ClientSidePlayerPrefab = null;
+            m_PrefabOverride = null;
+
+            yield return base.OnTearDown();
+        }
+
+
+        private GameObject GetPlayerNetworkPrefabObject(NetworkManager networkManager)
+        {
+            return networkManager.IsClient ? m_ClientSidePlayerPrefab.Prefab : m_PlayerPrefab;
+        }
+
+        [UnityTest]
+        public IEnumerator PrefabOverrideTests()
+        {
+            var prefabNetworkObject = (NetworkObject)null;
+            var spawnedGlobalObjectId = (uint)0;
+
+            var networkManagers = m_ClientNetworkManagers.ToList();
+            if (m_UseHost)
+            {
+                networkManagers.Insert(0, m_ServerNetworkManager);
+            }
+            else
+            {
+                // If running as just a server, validate that all player prefab clone instances are the server side version
+                prefabNetworkObject = GetPlayerNetworkPrefabObject(m_ServerNetworkManager).GetComponent<NetworkObject>();
+                foreach (var playerEntry in m_PlayerNetworkObjects[m_ServerNetworkManager.LocalClientId])
+                {
+                    spawnedGlobalObjectId = playerEntry.Value.GlobalObjectIdHash;
+                    Assert.IsTrue(prefabNetworkObject.GlobalObjectIdHash == spawnedGlobalObjectId, $"Server-Side {playerEntry.Value.name} was spawned as prefab ({spawnedGlobalObjectId}) but we expected ({prefabNetworkObject.GlobalObjectIdHash})!");
+                }
+            }
+
+            // Validates prefab overrides via the NetworkPrefabHandler.
+            // Validate the player prefab instance clones relative to all NetworkManagers.
+            foreach (var networkManager in networkManagers)
+            {
+                // Get the expected player prefab to be spawned based on the NetworkManager
+                prefabNetworkObject = GetPlayerNetworkPrefabObject(networkManager).GetComponent<NetworkObject>();
+                if (networkManager.IsClient)
+                {
+                    spawnedGlobalObjectId = networkManager.LocalClient.PlayerObject.GlobalObjectIdHash;
+                    Assert.IsTrue(prefabNetworkObject.GlobalObjectIdHash == spawnedGlobalObjectId, $"{networkManager.name} spawned player prefab ({spawnedGlobalObjectId}) did not match the expected one ({prefabNetworkObject.GlobalObjectIdHash})!");
+                }
+
+                foreach (var playerEntry in m_PlayerNetworkObjects[networkManager.LocalClientId])
+                {
+                    // We already checked our locally spawned player prefab above
+                    if (playerEntry.Key == networkManager.LocalClientId)
+                    {
+                        continue;
+                    }
+                    spawnedGlobalObjectId = playerEntry.Value.GlobalObjectIdHash;
+                    Assert.IsTrue(prefabNetworkObject.GlobalObjectIdHash == spawnedGlobalObjectId, $"Client-{networkManager.LocalClientId} clone of {playerEntry.Value.name} was spawned as prefab ({spawnedGlobalObjectId}) but we expected ({prefabNetworkObject.GlobalObjectIdHash})!");
+                }
+            }
+
+            // Validates prefab overrides via NetworkPrefab configuration.
+            var spawnedInstance = (NetworkObject)null;
+            var networkManagerOwner = m_ServerNetworkManager;
+
+            if (m_DistributedAuthority)
+            {
+                networkManagerOwner = m_ClientNetworkManagers[0];
+            }
+            // Clients and Host will spawn the OverridingTargetPrefab while a dedicated server will spawn the SourcePrefabToOverride
+            var expectedServerGlobalObjectIdHash = networkManagerOwner.IsClient ? m_PrefabOverride.OverridingTargetPrefab.GetComponent<NetworkObject>().GlobalObjectIdHash : m_PrefabOverride.SourcePrefabToOverride.GetComponent<NetworkObject>().GlobalObjectIdHash;
+            var expectedClientGlobalObjectIdHash = m_PrefabOverride.OverridingTargetPrefab.GetComponent<NetworkObject>().GlobalObjectIdHash;
+
+            spawnedInstance = NetworkObject.InstantiateAndSpawn(m_PrefabOverride.SourcePrefabToOverride, networkManagerOwner, networkManagerOwner.LocalClientId);
+            var builder = new StringBuilder();
+            bool ObjectSpawnedOnAllNetworkMangers()
+            {
+                builder.Clear();
+                if (!m_ServerNetworkManager.SpawnManager.SpawnedObjects.ContainsKey(spawnedInstance.NetworkObjectId))
+                {
+                    builder.AppendLine($"Client-{m_ServerNetworkManager.LocalClientId} failed to spawn {spawnedInstance.name}-{spawnedInstance.NetworkObjectId}!");
+                    return false;
+                }
+                var instanceGID = m_ServerNetworkManager.SpawnManager.SpawnedObjects[spawnedInstance.NetworkObjectId].GlobalObjectIdHash;
+                if (instanceGID != expectedServerGlobalObjectIdHash)
+                {
+                    builder.AppendLine($"Client-{m_ServerNetworkManager.LocalClientId} instance {spawnedInstance.name}-{spawnedInstance.NetworkObjectId} GID is {instanceGID} but was expected to be {expectedServerGlobalObjectIdHash}!");
+                    return false;
+                }
+
+                foreach (var networkManger in m_ClientNetworkManagers)
+                {
+                    if (!networkManger.SpawnManager.SpawnedObjects.ContainsKey(spawnedInstance.NetworkObjectId))
+                    {
+                        builder.AppendLine($"Client-{networkManger.LocalClientId} failed to spawn {spawnedInstance.name}-{spawnedInstance.NetworkObjectId}!");
+                        return false;
+                    }
+                    instanceGID = networkManger.SpawnManager.SpawnedObjects[spawnedInstance.NetworkObjectId].GlobalObjectIdHash;
+                    if (instanceGID != expectedClientGlobalObjectIdHash)
+                    {
+                        builder.AppendLine($"Client-{networkManger.LocalClientId} instance {spawnedInstance.name}-{spawnedInstance.NetworkObjectId} GID is {instanceGID} but was expected to be {expectedClientGlobalObjectIdHash}!");
+                        return false;
+                    }
+                }
+                return true;
+            }
+
+            yield return WaitForConditionOrTimeOut(ObjectSpawnedOnAllNetworkMangers);
+            AssertOnTimeout($"The spawned prefab override validation failed!\n {builder}");
+        }
+    }
+}

Tests/Runtime/Prefabs/NetworkPrefabOverrideTests.cs.meta

@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: c5e27e24bc5f783458d6a45585308f87