feat: client scene synchronization mode (#1171)

* refactor

This allows for two different types of client synchronization modes (ClientSynchronizationMode):
LoadSceneMode.Single: All currently loaded scenes on the client will be unloaded and the server's currently active scene will be loaded in single mode on the client unless it was already loaded.

LoadSceneMode.Additive:  All currently loaded scenes are left as they are and any newly loaded scenes will be loaded additively.  Uses need to determine which scenes are valid to load via the VerifySceneBeforeLoading method.

* refactor and style

Added the ability to squelch the validation warning messages for ClientSynchronizationMode additive as it will throw warnings for every loaded scene you don't want to have the client synchronize.

Updated the comments.

* style

fixing spelling typo.

* test

added Values to the scene loading test that will run the scene loading tests with client synchronization set to both LoadSceneMode.Single and LoadSceneMode.Additive.

* test

Adding verification that the client synchronization mode used by the server when building the client synchronization SceneEventData message is the same value on the client side.

* style

fixing whitespace issue

Author: NoelStephensUnity

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

@@ -205,6 +205,22 @@ public class NetworkSceneManager : IDisposable
 
         internal Scene DontDestroyOnLoadScene;
 
+        /// <summary>
+        /// LoadSceneMode.Single: All currently loaded scenes on the client will be unloaded and
+        /// the server's currently active scene will be loaded in single mode on the client
+        /// unless it was already loaded.
+        ///
+        /// LoadSceneMode.Additive: All currently loaded scenes are left as they are and any newly loaded
+        /// scenes will be loaded additively.  Users need to determine which scenes are valid to load via the
+        /// <see cref="VerifySceneBeforeLoading"/> method.
+        /// </summary>
+        public LoadSceneMode ClientSynchronizationMode { get; internal set; }
+
+        /// <summary>
+        /// When true, the <see cref="Debug.LogWarning(object)"/> messages will be turned off
+        /// </summary>
+        private bool m_DisableValidationWarningMessages;
+
         /// <summary>
         /// Handle NetworkSeneManager clean up
         /// </summary>
@@ -239,6 +255,32 @@ internal void GenerateScenesInBuild()
             }
         }
 
+        /// <summary>
+        /// When set to true, this will disable the console warnings about
+        /// a scene being invalidated.
+        /// </summary>
+        /// <param name="disabled"></param>
+        public void DisableValidationWarnings(bool disabled)
+        {
+            m_DisableValidationWarningMessages = disabled;
+        }
+
+        /// <summary>
+        /// This will change how clients are initially synchronized.
+        /// LoadSceneMode.Single: All currently loaded scenes on the client will be unloaded and
+        /// the server's currently active scene will be loaded in single mode on the client
+        /// unless it was already loaded.
+        ///
+        /// LoadSceneMode.Additive: All currently loaded scenes are left as they are and any newly loaded
+        /// scenes will be loaded additively.  Users need to determine which scenes are valid to load via the
+        /// <see cref="VerifySceneBeforeLoading"/> method.
+        /// </summary>
+        /// <param name="mode"><see cref="LoadSceneMode"/> for initial client synchronization</param>
+        public void SetClientSynchronizationMode(LoadSceneMode mode)
+        {
+            ClientSynchronizationMode = mode;
+        }
+
         /// <summary>
         /// Constructor
         /// </summary>
@@ -299,7 +341,7 @@ internal bool ValidateSceneBeforeLoading(uint sceneIndex, LoadSceneMode loadScen
             {
                 validated = VerifySceneBeforeLoading.Invoke((int)sceneIndex, sceneName, loadSceneMode);
             }
-            if (!validated)
+            if (!validated && !m_DisableValidationWarningMessages)
             {
                 var serverHostorClient = "Client";
                 if (m_NetworkManager.IsServer)
@@ -1139,7 +1181,7 @@ internal void SynchronizeNetworkObjects(ulong clientId)
 
             ClientSynchEventData.InitializeForSynch();
             ClientSynchEventData.TargetClientId = clientId;
-            ClientSynchEventData.LoadSceneMode = LoadSceneMode.Single;
+            ClientSynchEventData.LoadSceneMode = ClientSynchronizationMode;
             var activeScene = SceneManager.GetActiveScene();
             ClientSynchEventData.SceneEventType = SceneEventData.SceneEventTypes.S2C_Sync;
 
@@ -1158,7 +1200,7 @@ internal void SynchronizeNetworkObjects(ulong clientId)
                 // If we are the base scene, then we set the root scene index;
                 if (activeScene == scene)
                 {
-                    if (!ValidateSceneBeforeLoading(sceneIndex, LoadSceneMode.Single))
+                    if (!ValidateSceneBeforeLoading(sceneIndex, ClientSynchEventData.LoadSceneMode))
                     {
                         continue;
                     }

testproject/Assets/Tests/Runtime/NetworkSceneManagerTests.cs

@@ -43,7 +43,7 @@ private class SceneTestInfo
 
 
         [UnityTest]
-        public IEnumerator SceneLoadingAndNotifications()
+        public IEnumerator SceneLoadingAndNotifications([Values(LoadSceneMode.Single, LoadSceneMode.Additive)] LoadSceneMode clientSynchronizationMode)
         {
             m_ServerNetworkManager.SceneManager.OnSceneEvent += SceneManager_OnSceneEvent;
             m_CurrentSceneName = "AdditiveScene1";
@@ -85,7 +85,7 @@ public IEnumerator SceneLoadingAndNotifications()
 
 
             // Now prepare for the loading and unloading additive scene testing
-            InitializeSceneTestInfo();
+            InitializeSceneTestInfo(clientSynchronizationMode);
 
             // Test loading additive scenes and the associated event messaging and notification pipelines
             ResetWait();
@@ -139,12 +139,13 @@ public IEnumerator SceneLoadingAndNotifications()
         /// <summary>
         /// Initializes the m_ShouldWaitList
         /// </summary>
-        private void InitializeSceneTestInfo(bool enableSceneVerification = false)
+        private void InitializeSceneTestInfo(LoadSceneMode clientSynchronizationMode, bool enableSceneVerification = false)
         {
             m_ShouldWaitList.Add(new SceneTestInfo() { ClientId = m_ServerNetworkManager.ServerClientId, ShouldWait = false });
             if (enableSceneVerification)
             {
                 m_ServerNetworkManager.SceneManager.VerifySceneBeforeLoading = ServerVerifySceneBeforeLoading;
+                m_ServerNetworkManager.SceneManager.SetClientSynchronizationMode(clientSynchronizationMode);
             }
 
             foreach (var manager in m_ClientNetworkManagers)
@@ -153,6 +154,7 @@ private void InitializeSceneTestInfo(bool enableSceneVerification = false)
                 if (enableSceneVerification)
                 {
                     manager.SceneManager.VerifySceneBeforeLoading = ClientVerifySceneBeforeLoading;
+                    manager.SceneManager.SetClientSynchronizationMode(clientSynchronizationMode);
                 }
             }
         }
@@ -256,9 +258,16 @@ private void SceneManager_OnSceneEvent(SceneEvent sceneEvent)
         {
             switch (sceneEvent.SceneEventType)
             {
+                case SceneEventData.SceneEventTypes.S2C_Sync:
+                    {
+                        // Verify that the Client Synchronization Mode set by the server is being received by the client (which means it is applied when loading the first scene)
+                        Assert.AreEqual(m_ClientNetworkManagers.ToArray().Where(c => c.LocalClientId == sceneEvent.ClientId).First().SceneManager.ClientSynchronizationMode, sceneEvent.LoadSceneMode);
+                        break;
+                    }
                 case SceneEventData.SceneEventTypes.S2C_Load:
                 case SceneEventData.SceneEventTypes.S2C_Unload:
                     {
+
                         Assert.AreEqual(sceneEvent.SceneName, m_CurrentSceneName);
                         Assert.IsTrue(ContainsClient(sceneEvent.ClientId));
                         Assert.IsNotNull(sceneEvent.AsyncOperation);
@@ -342,13 +351,13 @@ private bool ClientVerifySceneBeforeLoading(int sceneIndex, string sceneName, Lo
         /// </summary>
         /// <returns></returns>
         [UnityTest]
-        public IEnumerator SceneVerifyBeforeLoadTest()
+        public IEnumerator SceneVerifyBeforeLoadTest([Values(LoadSceneMode.Single, LoadSceneMode.Additive)] LoadSceneMode clientSynchronizationMode)
         {
             m_ServerNetworkManager.SceneManager.OnSceneEvent += SceneManager_OnSceneEvent;
             m_CurrentSceneName = "AdditiveScene1";
 
             // Now prepare for the loading and unloading additive scene testing
-            InitializeSceneTestInfo(true);
+            InitializeSceneTestInfo(clientSynchronizationMode, true);
 
             // Test VerifySceneBeforeLoading with both server and client set to true
             ResetWait();