fix: NetworkSceneManager add do not load during callback note in xml documentation [MTT-3495] (#1974)

* update

xml documentation to be included in API documentation that one should not try to start a new scene event within a scene event notification callback.

* update

one more location just to make sure.

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

Co-authored-by: Fatih Mar <[email protected]>

Co-authored-by: Fatih Mar <[email protected]>

Author: NoelStephensUnity

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

@@ -12,6 +12,7 @@ namespace Unity.Netcode
     /// delegate type <see cref="NetworkSceneManager.SceneEventDelegate"/> uses this class to provide
     /// scene event status.<br/>
     /// <em>Note: This is only when <see cref="NetworkConfig.EnableSceneManagement"/> is enabled.</em><br/>
+    /// <em>*** Do not start new scene events within scene event notification callbacks.</em><br/>
     /// See also: <br/>
     /// <seealso cref="SceneEventType"/>
     /// </summary>
@@ -166,6 +167,7 @@ public class NetworkSceneManager : IDisposable
         /// <item><term><see cref="OnUnloadComplete"/> Invoked only when an <see cref="SceneEventType.UnloadComplete"/> event is being processed</term></item>
         /// <item><term><see cref="OnSynchronizeComplete"/> Invoked only when a <see cref="SceneEventType.SynchronizeComplete"/> event is being processed</term></item>
         /// </list>
+        /// <em>Note: Do not start new scene events within NetworkSceneManager scene event notification callbacks.</em><br/>
         /// </summary>
         public event SceneEventDelegate OnSceneEvent;
 
@@ -239,13 +241,15 @@ public class NetworkSceneManager : IDisposable
 
         /// <summary>
         /// Invoked when a <see cref="SceneEventType.Load"/> event is started by the server.<br/>
-        /// <em>Note: The server and connected client(s) will always receive this notification.</em>
+        /// <em>Note: The server and connected client(s) will always receive this notification.</em><br/>
+        /// <em>*** Do not start new scene events within scene event notification callbacks.</em><br/>
         /// </summary>
         public event OnLoadDelegateHandler OnLoad;
 
         /// <summary>
         /// Invoked when a <see cref="SceneEventType.Unload"/> event is started by the server.<br/>
-        /// <em>Note: The server and connected client(s) will always receive this notification.</em>
+        /// <em>Note: The server and connected client(s) will always receive this notification.</em><br/>
+        /// <em>*** Do not start new scene events within scene event notification callbacks.</em><br/>
         /// </summary>
         public event OnUnloadDelegateHandler OnUnload;
 
@@ -254,7 +258,8 @@ public class NetworkSceneManager : IDisposable
         /// after a client is approved for connection in order to synchronize the client with the currently loaded
         /// scenes and NetworkObjects.  This event signifies the beginning of the synchronization event.<br/>
         /// <em>Note: The server and connected client(s) will always receive this notification.
-        /// This event is generated on a per newly connected and approved client basis.</em>
+        /// This event is generated on a per newly connected and approved client basis.</em><br/>
+        /// <em>*** Do not start new scene events within scene event notification callbacks.</em><br/>
         /// </summary>
         public event OnSynchronizeDelegateHandler OnSynchronize;
 
@@ -263,7 +268,8 @@ public class NetworkSceneManager : IDisposable
         /// This event signifies the end of an existing <see cref="SceneEventType.Load"/> event as it pertains
         /// to all clients connected when the event was started.  This event signifies that all clients (and server) have
         /// finished the <see cref="SceneEventType.Load"/> event.<br/>
-        /// <em>Note: this is useful to know when all clients have loaded the same scene (single or additive mode)</em>
+        /// <em>Note: this is useful to know when all clients have loaded the same scene (single or additive mode)</em><br/>
+        /// <em>*** Do not start new scene events within scene event notification callbacks.</em><br/>
         /// </summary>
         public event OnEventCompletedDelegateHandler OnLoadEventCompleted;
 
@@ -273,21 +279,24 @@ public class NetworkSceneManager : IDisposable
         /// to all clients connected when the event was started.  This event signifies that all clients (and server) have
         /// finished the <see cref="SceneEventType.Unload"/> event.<br/>
         /// <em>Note: this is useful to know when all clients have unloaded a specific scene.  The <see cref="LoadSceneMode"/> will
-        /// always be <see cref="LoadSceneMode.Additive"/> for this event.</em>
+        /// always be <see cref="LoadSceneMode.Additive"/> for this event.</em><br/>
+        /// <em>*** Do not start new scene events within scene event notification callbacks.</em><br/>
         /// </summary>
         public event OnEventCompletedDelegateHandler OnUnloadEventCompleted;
 
         /// <summary>
         /// Invoked when a <see cref="SceneEventType.LoadComplete"/> event is generated by a client or server.<br/>
         /// <em>Note: The server receives this message from all clients (including itself).
-        /// Each client receives their own notification sent to the server.</em>
+        /// Each client receives their own notification sent to the server.</em><br/>
+        /// <em>*** Do not start new scene events within scene event notification callbacks.</em><br/>
         /// </summary>
         public event OnLoadCompleteDelegateHandler OnLoadComplete;
 
         /// <summary>
         /// Invoked when a <see cref="SceneEventType.UnloadComplete"/> event is generated by a client or server.<br/>
         /// <em>Note: The server receives this message from all clients (including itself).
-        /// Each client receives their own notification sent to the server.</em>
+        /// Each client receives their own notification sent to the server.</em><br/>
+        /// <em>*** Do not start new scene events within scene event notification callbacks.</em><br/>
         /// </summary>
         public event OnUnloadCompleteDelegateHandler OnUnloadComplete;
 
@@ -296,6 +305,7 @@ public class NetworkSceneManager : IDisposable
         /// <em> Note: The server receives this message from the client, but will never generate this event for itself.
         /// Each client receives their own notification sent to the server.  This is useful to know that a client has
         /// completed the entire connection sequence, loaded all scenes, and synchronized all NetworkObjects.</em>
+        /// <em>*** Do not start new scene events within scene event notification callbacks.</em><br/>
         /// </summary>
         public event OnSynchronizeCompleteDelegateHandler OnSynchronizeComplete;
 

testproject/Assets/Tests/Runtime/ObjectParenting/NetworkObjectParentingTests.cs

@@ -198,29 +198,40 @@ public IEnumerator Teardown()
             }
         }
 
+        private bool AllClientsSetCubeToPickupBackCube()
+        {
+            for (int setIndex = 0; setIndex < k_ClientInstanceCount; setIndex++)
+            {
+                if (m_Cube_NetObjs[setIndex + 1].parent != m_Pickup_Back_NetObjs[setIndex + 1])
+                {
+                    return false;
+                }
+
+                if (m_Cube_NetBhvs[setIndex + 1].ParentNetworkObject != m_Pickup_Back_NetObjs[setIndex + 1].GetComponent<NetworkObject>())
+                {
+                    return false;
+                }
+            }
+
+            return true;
+        }
+
         [UnityTest]
         public IEnumerator SetParentDirect()
         {
-            var waitForNetworkTick = new WaitForSeconds(1.0f / m_ServerNetworkManager.NetworkConfig.TickRate);
+            var timeoutHelper = new TimeoutHelper();
             // Server: Set/Cube -> Set/Pickup/Back/Cube
             m_Cube_NetObjs[0].parent = m_Pickup_Back_NetObjs[0];
             Assert.That(m_Cube_NetBhvs[0].ParentNetworkObject, Is.EqualTo(m_Pickup_Back_NetObjs[0].GetComponent<NetworkObject>()));
 
-            yield return waitForNetworkTick;
-
             // Client[n]: Set/Cube -> Set/Pickup/Back/Cube
-            for (int setIndex = 0; setIndex < k_ClientInstanceCount; setIndex++)
-            {
-                Assert.That(m_Cube_NetObjs[setIndex + 1].parent, Is.EqualTo(m_Pickup_Back_NetObjs[setIndex + 1]));
-                Assert.That(m_Cube_NetBhvs[setIndex + 1].ParentNetworkObject, Is.EqualTo(m_Pickup_Back_NetObjs[setIndex + 1].GetComponent<NetworkObject>()));
-            }
+            yield return NetcodeIntegrationTest.WaitForConditionOrTimeOut(AllClientsSetCubeToPickupBackCube, timeoutHelper);
+            Assert.False(timeoutHelper.TimedOut, "TImed out waiting for Client[n]: Set/Cube -> Set/Pickup/Back/Cube");
 
             // Server: Set/Pickup/Back -> Root/Cube
             m_Cube_NetObjs[0].parent = null;
             Assert.That(m_Cube_NetBhvs[0].ParentNetworkObject, Is.EqualTo(null));
 
-            yield return waitForNetworkTick;
-
             bool CheckClientSideCubeForNull()
             {
                 // Client[n]: Set/Pickup/Back -> Root/Cube
@@ -233,7 +244,6 @@ bool CheckClientSideCubeForNull()
                 }
                 return true;
             }
-            var timeoutHelper = new TimeoutHelper();
             yield return NetcodeIntegrationTest.WaitForConditionOrTimeOut(CheckClientSideCubeForNull, timeoutHelper);
             Assert.False(timeoutHelper.TimedOut, $"Timed out waiting for client parent to be null!");