feat: add pre and post spawn methods (#2906)

* update

adding pre and post spawn methods.
clearing the m_ChildNetworkBehaviours on Awake.

* update

adding change log entries

* update

Needed to add a NetworkManager ref into the pre spawn method.
Needed to account for locally spawning.

* test

Adding test that validates the pre spawn and post spawn methods are invoked and that order of operations for OnNetworkSpawn invocation is not an issue with OnNetworkPostSpawn invocation.

* style

updating comments

* style

updating comments a bit more

* test

Migrating OnDynamicNetworkPreAndPostSpawn into its own class to avoid interfering with the generic tests.

* style

removing property no longer used and remove LF/CR

* update and test

Added NetworkBehaviour.OnNetworkSessionSynchronized and NetworkBehaviour.OnInSceneObjectsSpawned methods.

Added test to validate the above methods.

Added assets for the test to validate the above methods.

Author: NoelStephensUnity

com.unity.netcode.gameobjects/CHANGELOG.md

@@ -6,6 +6,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 Additional documentation and release notes are available at [Multiplayer Documentation](https://docs-multiplayer.unity3d.com).
 
+## [Unreleased]
+
+### Added
+
+- Added `NetworkBehaviour.OnNetworkPreSpawn` and `NetworkBehaviour.OnNetworkPostSpawn` methods that provide the ability to handle pre and post spawning actions during the `NetworkObject` spawn sequence. (#2906)
+- Added a client-side only `NetworkBehaviour.OnNetworkSessionSynchronized` convenience method that is invoked on all `NetworkBehaviour`s after a newly joined client has finished synchronizing with the network session in progress. (#2906)
+- Added `NetworkBehaviour.OnInSceneObjectsSpawned` convenience method that is invoked when all in-scene `NetworkObject`s have been spawned after a scene has been loaded or upon a host or server starting. (#2906)
+
+### Fixed
+
+- Fixed issue where a `NetworkObject` component's associated `NetworkBehaviour` components would not be detected if scene loading is disabled in the editor and the currently loaded scene has in-scene placed `NetworkObject`s. (#2906)
+
+### Changed
+
+
 ## [1.9.1] - 2024-04-18
 
 ### Added

com.unity.netcode.gameobjects/Runtime/Core/NetworkBehaviour.cs

@@ -615,16 +615,70 @@ internal void UpdateNetworkProperties()
             }
         }
 
+        /// <summary>
+        /// Gets called after the <see cref="NetworkObject"/> is spawned. No NetworkBehaviours associated with the NetworkObject will have had <see cref="OnNetworkSpawn"/> invoked yet.
+        /// A reference to <see cref="NetworkManager"/> is passed in as a parameter to determine the context of execution (IsServer/IsClient)
+        /// </summary>
+        /// <remarks>
+        /// <param name="networkManager">a ref to the <see cref="NetworkManager"/> since this is not yet set on the <see cref="NetworkBehaviour"/></param>
+        /// The <see cref="NetworkBehaviour"/> will not have anything assigned to it at this point in time.
+        /// Settings like ownership, NetworkBehaviourId, NetworkManager, and most other spawn related properties will not be set.
+        /// This can be used to handle things like initializing/instantiating a NetworkVariable or the like.
+        /// </remarks>
+        protected virtual void OnNetworkPreSpawn(ref NetworkManager networkManager) { }
+
         /// <summary>
         /// Gets called when the <see cref="NetworkObject"/> gets spawned, message handlers are ready to be registered and the network is setup.
         /// </summary>
         public virtual void OnNetworkSpawn() { }
 
+        /// <summary>
+        /// Gets called after the <see cref="NetworkObject"/> is spawned. All NetworkBehaviours associated with the NetworkObject will have had <see cref="OnNetworkSpawn"/> invoked.
+        /// </summary>
+        /// <remarks>
+        /// Will be invoked on each <see cref="NetworkBehaviour"/> associated with the <see cref="NetworkObject"/> being spawned.
+        /// All associated <see cref="NetworkBehaviour"/> components will have had <see cref="OnNetworkSpawn"/> invoked on the spawned <see cref="NetworkObject"/>.
+        /// </remarks>
+        protected virtual void OnNetworkPostSpawn() { }
+
+        /// <summary>
+        /// [Client-Side Only]
+        /// When a new client joins it is synchronized with all spawned NetworkObjects and scenes loaded for the session joined. At the end of the synchronization process, when all
+        /// <see cref="NetworkObject"/>s and scenes (if scene management is enabled) have finished synchronizing, all NetworkBehaviour components associated with spawned <see cref="NetworkObject"/>s
+        /// will have this method invoked.
+        /// </summary>
+        /// <remarks>
+        /// This can be used to handle post synchronization actions where you might need to access a different NetworkObject and/or NetworkBehaviour not local to the current NetworkObject context.
+        /// This is only invoked on clients during a client-server network topology session.
+        /// </remarks>
+        protected virtual void OnNetworkSessionSynchronized() { }
+
+        /// <summary>
+        /// [Client & Server Side]
+        /// When a scene is loaded an in-scene placed NetworkObjects are all spawned, this method is invoked on all of the newly spawned in-scene placed NetworkObjects.
+        /// </summary>
+        /// <remarks>
+        /// This can be used to handle post scene loaded actions for in-scene placed NetworkObjcts where you might need to access a different NetworkObject and/or NetworkBehaviour not local to the current NetworkObject context.
+        /// </remarks>
+        protected virtual void OnInSceneObjectsSpawned() { }
+
         /// <summary>
         /// Gets called when the <see cref="NetworkObject"/> gets despawned. Is called both on the server and clients.
         /// </summary>
         public virtual void OnNetworkDespawn() { }
 
+        internal void NetworkPreSpawn(ref NetworkManager networkManager)
+        {
+            try
+            {
+                OnNetworkPreSpawn(ref networkManager);
+            }
+            catch (Exception e)
+            {
+                Debug.LogException(e);
+            }
+        }
+
         internal void InternalOnNetworkSpawn()
         {
             IsSpawned = true;
@@ -653,6 +707,42 @@ internal void VisibleOnNetworkSpawn()
             }
         }
 
+        internal void NetworkPostSpawn()
+        {
+            try
+            {
+                OnNetworkPostSpawn();
+            }
+            catch (Exception e)
+            {
+                Debug.LogException(e);
+            }
+        }
+
+        internal void NetworkSessionSynchronized()
+        {
+            try
+            {
+                OnNetworkSessionSynchronized();
+            }
+            catch (Exception e)
+            {
+                Debug.LogException(e);
+            }
+        }
+
+        internal void InSceneNetworkObjectsSpawned()
+        {
+            try
+            {
+                OnInSceneObjectsSpawned();
+            }
+            catch (Exception e)
+            {
+                Debug.LogException(e);
+            }
+        }
+
         internal void InternalOnNetworkDespawn()
         {
             IsSpawned = false;

com.unity.netcode.gameobjects/Runtime/Core/NetworkObject.cs

@@ -512,6 +512,7 @@ internal int GetSceneOriginHandle()
 
         private void Awake()
         {
+            m_ChildNetworkBehaviours = null;
             SetCachedParent(transform.parent);
             SceneOrigin = gameObject.scene;
         }
@@ -1360,6 +1361,18 @@ internal static void CheckOrphanChildren()
             }
         }
 
+        internal void InvokeBehaviourNetworkPreSpawn()
+        {
+            var networkManager = NetworkManager;
+            for (int i = 0; i < ChildNetworkBehaviours.Count; i++)
+            {
+                if (ChildNetworkBehaviours[i].gameObject.activeInHierarchy)
+                {
+                    ChildNetworkBehaviours[i].NetworkPreSpawn(ref networkManager);
+                }
+            }
+        }
+
         internal void InvokeBehaviourNetworkSpawn()
         {
             NetworkManager.SpawnManager.UpdateOwnershipTable(this, OwnerClientId);
@@ -1384,6 +1397,42 @@ internal void InvokeBehaviourNetworkSpawn()
             }
         }
 
+        internal void InvokeBehaviourNetworkPostSpawn()
+        {
+            for (int i = 0; i < ChildNetworkBehaviours.Count; i++)
+            {
+                if (ChildNetworkBehaviours[i].gameObject.activeInHierarchy)
+                {
+                    ChildNetworkBehaviours[i].NetworkPostSpawn();
+                }
+            }
+        }
+
+
+        internal void InternalNetworkSessionSynchronized()
+        {
+            for (int i = 0; i < ChildNetworkBehaviours.Count; i++)
+            {
+                if (ChildNetworkBehaviours[i].gameObject.activeInHierarchy)
+                {
+                    ChildNetworkBehaviours[i].NetworkSessionSynchronized();
+                }
+            }
+        }
+
+        internal void InternalInSceneNetworkObjectsSpawned()
+        {
+            for (int i = 0; i < ChildNetworkBehaviours.Count; i++)
+            {
+                if (ChildNetworkBehaviours[i].gameObject.activeInHierarchy)
+                {
+                    ChildNetworkBehaviours[i].InSceneNetworkObjectsSpawned();
+                }
+            }
+        }
+
+
+
         internal void InvokeBehaviourNetworkDespawn()
         {
             NetworkManager.SpawnManager.UpdateOwnershipTable(this, OwnerClientId, true);
@@ -1886,6 +1935,9 @@ internal static NetworkObject AddSceneObject(in SceneObject sceneObject, FastBuf
             // in order to be able to determine which NetworkVariables the client will be allowed to read.
             networkObject.OwnerClientId = sceneObject.OwnerClientId;
 
+            // Special Case: Invoke NetworkBehaviour.OnPreSpawn methods here before SynchronizeNetworkBehaviours
+            networkObject.InvokeBehaviourNetworkPreSpawn();
+
             // Synchronize NetworkBehaviours
             var bufferSerializer = new BufferSerializer<BufferSerializerReader>(new BufferSerializerReader(reader));
             networkObject.SynchronizeNetworkBehaviours(ref bufferSerializer, networkManager.LocalClientId);

com.unity.netcode.gameobjects/Runtime/Messaging/Messages/ConnectionApprovedMessage.cs

@@ -170,6 +170,12 @@ public void Handle(ref NetworkContext context)
                 networkManager.IsConnectedClient = true;
                 // When scene management is disabled we notify after everything is synchronized
                 networkManager.ConnectionManager.InvokeOnClientConnectedCallback(context.SenderId);
+
+                // For convenience, notify all NetworkBehaviours that synchronization is complete.
+                foreach (var networkObject in networkManager.SpawnManager.SpawnedObjectsList)
+                {
+                    networkObject.InternalNetworkSessionSynchronized();
+                }
             }
 
             ConnectedClientIds.Dispose();

com.unity.netcode.gameobjects/Runtime/SceneManagement/NetworkSceneManager.cs

@@ -1688,6 +1688,17 @@ private void OnServerLoadedScene(uint sceneEventId, Scene scene)
                 }
             }
 
+            foreach (var keyValuePairByGlobalObjectIdHash in ScenePlacedObjects)
+            {
+                foreach (var keyValuePairBySceneHandle in keyValuePairByGlobalObjectIdHash.Value)
+                {
+                    if (!keyValuePairBySceneHandle.Value.IsPlayerObject)
+                    {
+                        keyValuePairBySceneHandle.Value.InternalInSceneNetworkObjectsSpawned();
+                    }
+                }
+            }
+
             // Add any despawned when spawned in-scene placed NetworkObjects to the scene event data
             sceneEventData.AddDespawnedInSceneNetworkObjects();
 
@@ -2142,6 +2153,12 @@ private void HandleClientSceneEvent(uint sceneEventId)
 
                             OnSynchronizeComplete?.Invoke(NetworkManager.LocalClientId);
 
+                            // For convenience, notify all NetworkBehaviours that synchronization is complete.
+                            foreach (var networkObject in NetworkManager.SpawnManager.SpawnedObjectsList)
+                            {
+                                networkObject.InternalNetworkSessionSynchronized();
+                            }
+
                             EndSceneEvent(sceneEventId);
                         }
                         break;

com.unity.netcode.gameobjects/Runtime/SceneManagement/SceneEventData.cs

@@ -722,7 +722,7 @@ internal void DeserializeScenePlacedObjects()
             {
                 // is not packed!
                 InternalBuffer.ReadValueSafe(out ushort newObjectsCount);
-
+                var sceneObjects = new List<NetworkObject>();
                 for (ushort i = 0; i < newObjectsCount; i++)
                 {
                     var sceneObject = new NetworkObject.SceneObject();
@@ -734,10 +734,22 @@ internal void DeserializeScenePlacedObjects()
                         m_NetworkManager.SceneManager.SetTheSceneBeingSynchronized(sceneObject.NetworkSceneHandle);
                     }
 
-                    NetworkObject.AddSceneObject(sceneObject, InternalBuffer, m_NetworkManager);
+                    var networkObject = NetworkObject.AddSceneObject(sceneObject, InternalBuffer, m_NetworkManager);
+
+                    if (sceneObject.IsSceneObject)
+                    {
+                        sceneObjects.Add(networkObject);
+                    }
                 }
                 // Now deserialize the despawned in-scene placed NetworkObjects list (if any)
                 DeserializeDespawnedInScenePlacedNetworkObjects();
+
+                // Notify all newly spawned in-scene placed NetworkObjects that all in-scene placed
+                // NetworkObjects have been spawned.
+                foreach (var networkObject in sceneObjects)
+                {
+                    networkObject.InternalInSceneNetworkObjectsSpawned();
+                }
             }
             finally
             {
@@ -983,6 +995,15 @@ internal void SynchronizeSceneNetworkObjects(NetworkManager networkManager)
                     }
                 }
 
+                // Notify that all in-scene placed NetworkObjects have been spawned
+                foreach (var networkObject in m_NetworkObjectsSync)
+                {
+                    if (networkObject.IsSceneObject.HasValue && networkObject.IsSceneObject.Value)
+                    {
+                        networkObject.InternalInSceneNetworkObjectsSpawned();
+                    }
+                }
+
                 // Now deserialize the despawned in-scene placed NetworkObjects list (if any)
                 DeserializeDespawnedInScenePlacedNetworkObjects();
 

com.unity.netcode.gameobjects/Runtime/Serialization/NetworkBehaviourReference.cs

@@ -45,7 +45,7 @@ public NetworkBehaviourReference(NetworkBehaviour networkBehaviour)
         /// <returns>True if the <see cref="NetworkBehaviour"/> was found; False if the <see cref="NetworkBehaviour"/> was not found. This can happen if the corresponding <see cref="NetworkObject"/> has not been spawned yet. you can try getting the reference at a later point in time.</returns>
         public bool TryGet(out NetworkBehaviour networkBehaviour, NetworkManager networkManager = null)
         {
-            networkBehaviour = GetInternal(this, null);
+            networkBehaviour = GetInternal(this, networkManager);
             return networkBehaviour != null;
         }
 
@@ -58,7 +58,7 @@ public bool TryGet(out NetworkBehaviour networkBehaviour, NetworkManager network
         /// <returns>True if the <see cref="NetworkBehaviour"/> was found; False if the <see cref="NetworkBehaviour"/> was not found. This can happen if the corresponding <see cref="NetworkObject"/> has not been spawned yet. you can try getting the reference at a later point in time.</returns>
         public bool TryGet<T>(out T networkBehaviour, NetworkManager networkManager = null) where T : NetworkBehaviour
         {
-            networkBehaviour = GetInternal(this, null) as T;
+            networkBehaviour = GetInternal(this, networkManager) as T;
             return networkBehaviour != null;
         }
 

com.unity.netcode.gameobjects/Runtime/Spawning/NetworkSpawnManager.cs

@@ -604,7 +604,12 @@ internal NetworkObject CreateLocalNetworkObject(NetworkObject.SceneObject sceneO
             return networkObject;
         }
 
-        // Ran on both server and client
+        /// <summary>
+        /// Invoked when spawning locally
+        /// </summary>
+        /// <remarks>
+        /// Pre and Post spawn methods *CAN* be invoked prior to invoking <see cref="SpawnNetworkObjectLocallyCommon"/>
+        /// </remarks>
         internal void SpawnNetworkObjectLocally(NetworkObject networkObject, ulong networkId, bool sceneObject, bool playerObject, ulong ownerClientId, bool destroyWithScene)
         {
             if (networkObject == null)
@@ -625,11 +630,21 @@ internal void SpawnNetworkObjectLocally(NetworkObject networkObject, ulong netwo
                     Debug.LogError("Spawning NetworkObjects with nested NetworkObjects is only supported for scene objects. Child NetworkObjects will not be spawned over the network!");
                 }
             }
+            // Invoke NetworkBehaviour.OnPreSpawn methods
+            networkObject.InvokeBehaviourNetworkPreSpawn();
 
             SpawnNetworkObjectLocallyCommon(networkObject, networkId, sceneObject, playerObject, ownerClientId, destroyWithScene);
+
+            // Invoke NetworkBehaviour.OnPostSpawn methods
+            networkObject.InvokeBehaviourNetworkPostSpawn();
         }
 
-        // Ran on both server and client
+        /// <summary>
+        /// Invoked from AddSceneObject
+        /// </summary>
+        /// <remarks>
+        /// IMPORTANT: Pre spawn methods need to be invoked from within <see cref="NetworkObject.AddSceneObject"/>.
+        /// </remarks>
         internal void SpawnNetworkObjectLocally(NetworkObject networkObject, in NetworkObject.SceneObject sceneObject, bool destroyWithScene)
         {
             if (networkObject == null)
@@ -642,7 +657,11 @@ internal void SpawnNetworkObjectLocally(NetworkObject networkObject, in NetworkO
                 throw new SpawnStateException("Object is already spawned");
             }
 
+            // Do not invoke Pre spawn here (SynchronizeNetworkBehaviours needs to be invoked prior to this)
             SpawnNetworkObjectLocallyCommon(networkObject, sceneObject.NetworkObjectId, sceneObject.IsSceneObject, sceneObject.IsPlayerObject, sceneObject.OwnerClientId, destroyWithScene);
+
+            // It is ok to invoke NetworkBehaviour.OnPostSpawn methods
+            networkObject.InvokeBehaviourNetworkPostSpawn();
         }
 
         private void SpawnNetworkObjectLocallyCommon(NetworkObject networkObject, ulong networkId, bool sceneObject, bool playerObject, ulong ownerClientId, bool destroyWithScene)
@@ -948,11 +967,16 @@ internal void ServerSpawnSceneObjectsOnStartSweep()
                 }
             }
 
-
             foreach (var networkObject in networkObjectsToSpawn)
             {
                 SpawnNetworkObjectLocally(networkObject, GetNetworkObjectId(), true, false, networkObject.OwnerClientId, true);
             }
+
+            // Notify all in-scene placed NetworkObjects have been spawned
+            foreach (var networkObject in networkObjectsToSpawn)
+            {
+                networkObject.InternalInSceneNetworkObjectsSpawned();
+            }
         }
 
         internal void OnDespawnObject(NetworkObject networkObject, bool destroyGameObject)