feat: consolidate simplification (#50)

BREAKING CHANGE: The 4.x update consolidates the changes in the 3.x and simplifies a few more steps of the usage experience. It completely removes the ISceneLoader implementations and adds a static MySceneManager class so you don't have to manually control its lifecycle. Refer to the upgrade guide at https://scene-loader.mygamedevtools.com/docs/upgrades/from-3-to-4 for more details.

Author: joaoborks

LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 MyGameDevTools
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

LICENSE.txt.meta

@@ -1,11 +1,6 @@
-#if ENABLE_UNITASK && !OVERRIDE_DISABLE_UNITASK
-#define USE_UNITASK
-#endif
-#if USE_UNITASK
-using Cysharp.Threading.Tasks;
-#endif
 using System;
 using System.Collections.Generic;
+using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
 using UnityEngine;
@@ -14,9 +9,9 @@
 namespace MyGameDevTools.SceneLoading
 {
     /// <summary>
-    /// The <see cref="AdvancedSceneManager"/> is capable of managing both addressable and non-addressable scene operations.
+    /// The <see cref="CoreSceneManager"/> is capable of managing both addressable and non-addressable scene operations.
     /// </summary>
-    public class AdvancedSceneManager : ISceneManager
+    public class CoreSceneManager : ISceneManager
     {
         public event Action<Scene, Scene> ActiveSceneChanged;
         public event Action<Scene> SceneUnloaded;
@@ -32,15 +27,15 @@ public class AdvancedSceneManager : ISceneManager
         ISceneData _activeScene;
 
         /// <summary>
-        /// Creates an <see cref="AdvancedSceneManager"/> with no initial scene references.
+        /// Creates a <see cref="CoreSceneManager"/> with no initial scene references.
         /// </summary>
-        public AdvancedSceneManager() : this(false) { }
+        public CoreSceneManager() : this(false) { }
         /// <summary>
-        /// Creates a new <see cref="AdvancedSceneManager"/> with the option to add all loaded scenes to its management.
+        /// Creates a new <see cref="CoreSceneManager"/> with the option to add all loaded scenes to its management.
         /// The advantage is that you can manage those scenes through this <see cref="ISceneManager"/> instead of having to
         /// use the Unity <see cref="SceneManager"/>.
         /// </summary>
-        public AdvancedSceneManager(bool addLoadedScenes)
+        public CoreSceneManager(bool addLoadedScenes)
         {
             if (!addLoadedScenes)
             {
@@ -63,19 +58,19 @@ public AdvancedSceneManager(bool addLoadedScenes)
             }
             else if (loadedSceneCount == 0)
             {
-                Debug.LogWarning("Tried to create an `AdvancedSceneManager` with all loaded scenes, but encoutered none. Did you create the scene manager on `Awake()`? If so, try moving the call to `Start()` instead.");
+                Debug.LogWarning("Tried to create a Scene Manager with all loaded scenes, but encoutered none. Did you create the Scene Manager on `Awake()`? If so, try moving the call to `Start()` instead.");
             }
         }
         /// <summary>
-        /// Creates a new <see cref="AdvancedSceneManager"/> with the option to add a list of loaded scenes to its management.
+        /// Creates a new <see cref="CoreSceneManager"/> with the option to add a list of loaded scenes to its management.
         /// The advantage is that you can manage those scenes through this <see cref="ISceneManager"/> instead of having to
         /// use the Unity <see cref="SceneManager"/>.
         /// </summary>
-        public AdvancedSceneManager(Scene[] initializationScenes)
+        public CoreSceneManager(Scene[] initializationScenes)
         {
             if (initializationScenes == null || initializationScenes.Length == 0)
             {
-                throw new ArgumentException($"Trying to create an {nameof(AdvancedSceneManager)} with a null or empty array of initialization scenes. If you want to create it without any scenes, use the empty constructor instead.", nameof(initializationScenes));
+                throw new ArgumentException($"Trying to create an {nameof(CoreSceneManager)} with a null or empty array of initialization scenes. If you want to create it without any scenes, use the empty constructor instead.", nameof(initializationScenes));
             }
 
             int loadedSceneCount = initializationScenes.Length;
@@ -141,45 +136,34 @@ public Scene GetLoadedSceneByName(string name)
             throw new ArgumentException($"[{GetType().Name}] Could not find any loaded scene with the name '{name}'.", nameof(name));
         }
 
-        public async ValueTask<Scene[]> LoadScenesAsync(ILoadSceneInfo[] sceneInfos, int setIndexActive = -1, IProgress<float> progress = null, CancellationToken token = default)
+        public Task<SceneResult> TransitionAsync(SceneParameters sceneParameters, ILoadSceneInfo intermediateSceneReference = null, CancellationToken token = default)
         {
-            CancellationTokenSource linkedSource = CancellationTokenSource.CreateLinkedTokenSource(_lifetimeTokenSource.Token, token);
-            return await LoadScenesAsync_Internal(sceneInfos, setIndexActive, progress, linkedSource.Token).RunAndDisposeToken(linkedSource);
-        }
-
-        public async ValueTask<Scene> LoadSceneAsync(ILoadSceneInfo sceneInfo, bool setActive = false, IProgress<float> progress = null, CancellationToken token = default)
-        {
-            sceneInfo = sceneInfo ?? throw new NullReferenceException($"[{GetType().Name}] Provided scene info is null.");
+            if (!sceneParameters.ShouldSetActive())
+                throw new ArgumentException($"[{GetType().Name}] You need to provide a SceneParameters object with a valid 'setIndexActive' value to perform scene transitions.", nameof(sceneParameters));
 
             CancellationTokenSource linkedSource = CancellationTokenSource.CreateLinkedTokenSource(_lifetimeTokenSource.Token, token);
-            Scene[] loadedScenes = await LoadScenesAsync_Internal(new ILoadSceneInfo[] { sceneInfo }, setActive ? 0 : -1, progress, linkedSource.Token).RunAndDisposeToken(linkedSource);
-
-            return loadedScenes != null && loadedScenes.Length > 0 ? loadedScenes[0] : default;
+            return intermediateSceneReference == null
+                ? TransitionDirectlyAsync(sceneParameters, linkedSource.Token).RunAndDisposeToken(linkedSource)
+                : TransitionWithIntermediateAsync(sceneParameters, intermediateSceneReference, linkedSource.Token).RunAndDisposeToken(linkedSource);
         }
 
-        public async ValueTask<Scene[]> UnloadScenesAsync(ILoadSceneInfo[] sceneInfos, CancellationToken token = default)
+        public Task<SceneResult> LoadAsync(SceneParameters sceneParameters, IProgress<float> progress = null, CancellationToken token = default)
         {
             CancellationTokenSource linkedSource = CancellationTokenSource.CreateLinkedTokenSource(_lifetimeTokenSource.Token, token);
-            return await UnloadScenesAsync_Internal(sceneInfos, linkedSource.Token).RunAndDisposeToken(linkedSource);
+            return LoadScenesAsync_Internal(sceneParameters, progress, linkedSource.Token).RunAndDisposeToken(linkedSource);
         }
 
-        public async ValueTask<Scene> UnloadSceneAsync(ILoadSceneInfo sceneInfo, CancellationToken token = default)
+        public Task<SceneResult> UnloadAsync(SceneParameters sceneParameters, CancellationToken token = default)
         {
-            sceneInfo = sceneInfo ?? throw new ArgumentNullException(nameof(sceneInfo), $"[{GetType().Name}] Provided scene info is null.");
-
             CancellationTokenSource linkedSource = CancellationTokenSource.CreateLinkedTokenSource(_lifetimeTokenSource.Token, token);
-            Scene[] unloadedScenes = await UnloadScenesAsync_Internal(new ILoadSceneInfo[] { sceneInfo }, linkedSource.Token).RunAndDisposeToken(linkedSource);
-
-            return unloadedScenes != null && unloadedScenes.Length > 0 ? unloadedScenes[0] : default;
+            return UnloadScenesAsync_Internal(sceneParameters.GetLoadSceneInfos(), linkedSource.Token).RunAndDisposeToken(linkedSource);
         }
 
-        async ValueTask<Scene[]> LoadScenesAsync_Internal(ILoadSceneInfo[] sceneInfos, int setIndexActive, IProgress<float> progress, CancellationToken token)
+        async Task<SceneResult> LoadScenesAsync_Internal(SceneParameters sceneParameters, IProgress<float> progress, CancellationToken token)
         {
+            ILoadSceneInfo[] sceneInfos = sceneParameters.GetLoadSceneInfos();
+            int setIndexActive = sceneParameters.GetIndexToActivate();
             int scenesToLoad = sceneInfos.Length;
-            if (sceneInfos == null || scenesToLoad == 0)
-                throw new ArgumentException(nameof(sceneInfos), $"[{GetType().Name}] Provided scene group is null or empty.");
-            if (setIndexActive >= scenesToLoad)
-                throw new ArgumentException(nameof(setIndexActive), $"[{GetType().Name}] Provided index to set active is bigger than the provided scene group size.");
 
             ISceneData[] sceneDataArray = new ISceneData[scenesToLoad];
             int i;
@@ -189,15 +173,7 @@ async ValueTask<Scene[]> LoadScenesAsync_Internal(ILoadSceneInfo[] sceneInfos, i
                 sceneDataArray[i].LoadSceneAsync();
             }
 
-            while (!SceneDataUtilities.HasCompletedAllSceneLoadOperations(sceneDataArray) && !token.IsCancellationRequested)
-            {
-#if USE_UNITASK
-                await UniTask.Yield(token);
-#else
-                await Task.Yield();
-#endif
-                progress?.Report(SceneDataUtilities.GetAverageSceneLoadOperationProgress(sceneDataArray));
-            }
+            await PollProgressAsync(sceneDataArray, progress, token);
 
             token.ThrowIfCancellationRequested();
 
@@ -212,37 +188,40 @@ async ValueTask<Scene[]> LoadScenesAsync_Internal(ILoadSceneInfo[] sceneInfos, i
             if (setIndexActive >= 0)
                 SetActiveScene(sceneDataArray[setIndexActive].SceneReference);
 
-            return SceneDataUtilities.GetScenesFromSceneDataArray(sceneDataArray);
+            return new SceneResult(SceneDataUtilities.GetScenesFromSceneDataArray(sceneDataArray));
         }
 
-        async ValueTask<Scene[]> UnloadScenesAsync_Internal(ILoadSceneInfo[] sceneInfos, CancellationToken token)
+        async Task<SceneResult> UnloadScenesAsync_Internal(ILoadSceneInfo[] sceneInfos, CancellationToken token)
         {
             if (sceneInfos == null || sceneInfos.Length == 0)
                 throw new ArgumentException($"[{GetType().Name}] Provided scene group is null or empty.", nameof(sceneInfos));
 
+            int sceneCount = sceneInfos.Length;
             ISceneData[] sceneDataArray = SceneDataUtilities.GetLoadedSceneDatasWithLoadSceneInfos(sceneInfos, _loadedScenes);
+            Task[] loadTasks = new Task[sceneCount];
 
-            int sceneCount = sceneInfos.Length;
             ISceneData tempSceneData;
             int i;
             for (i = 0; i < sceneCount; i++)
             {
                 tempSceneData = sceneDataArray[i];
                 _loadedScenes.Remove(tempSceneData);
                 _unloadingScenes.Add(tempSceneData);
-                tempSceneData.UnloadSceneAsync();
+                loadTasks[i] = UnityTaskUtilities.FromAsyncOperation(sceneDataArray[i].UnloadSceneAsync(), token);
             }
 
-            while (!SceneDataUtilities.HasCompletedAllSceneLoadOperations(sceneDataArray) && !token.IsCancellationRequested)
+            try
             {
-#if USE_UNITASK
-                await UniTask.Yield(token);
-#else
-                await Task.Yield();
-#endif
+                await Task.WhenAll(loadTasks);
+            }
+            catch (OperationCanceledException exception)
+            {
+                for (i = 0; i < sceneCount; i++)
+                {
+                    _unloadingScenes.Remove(sceneDataArray[i]);
+                }
+                throw exception;
             }
-
-            token.ThrowIfCancellationRequested();
 
             for (i = 0; i < sceneCount; i++)
             {
@@ -253,7 +232,80 @@ async ValueTask<Scene[]> UnloadScenesAsync_Internal(ILoadSceneInfo[] sceneInfos,
                     SetActiveScene(GetLastLoadedScene());
             }
 
-            return SceneDataUtilities.GetScenesFromSceneDataArray(sceneDataArray);
+            return new SceneResult(SceneDataUtilities.GetScenesFromSceneDataArray(sceneDataArray));
+        }
+
+        async Task<SceneResult> TransitionDirectlyAsync(SceneParameters sceneParameters, CancellationToken token)
+        {
+            // If only one scene is loaded, create a temporary scene for transition.
+            Scene tempScene = default;
+            if (LoadedSceneCount <= 1)
+            {
+                tempScene = SceneManager.CreateScene("temp-transition-scene");
+            }
+            await UnloadSourceSceneAsync(token);
+
+            Scene[] loadedScenes = await LoadAsync(sceneParameters, token: token);
+
+            if (tempScene.IsValid())
+            {
+                IAsyncSceneOperation unloadOperation = new AsyncSceneOperationStandard(SceneManager.UnloadSceneAsync(tempScene));
+                await UnityTaskUtilities.FromAsyncOperation(unloadOperation, token);
+            }
+            return new SceneResult(loadedScenes);
+        }
+
+        async Task<SceneResult> TransitionWithIntermediateAsync(SceneParameters sceneParameters, ILoadSceneInfo intermediateSceneInfo, CancellationToken token)
+        {
+            Scene loadingScene = await LoadAsync(new SceneParameters(intermediateSceneInfo, false), token: token);
+            intermediateSceneInfo = new LoadSceneInfoScene(loadingScene);
+
+            LoadingBehavior loadingBehavior = UnityEngine.Object.FindObjectsByType<LoadingBehavior>(FindObjectsSortMode.None).FirstOrDefault(l => l.gameObject.scene == loadingScene);
+            return loadingBehavior
+                ? await TransitionWithIntermediateLoadingAsync(sceneParameters, intermediateSceneInfo, loadingBehavior, token)
+                : await TransitionWithIntermediateNoLoadingAsync(sceneParameters, intermediateSceneInfo, token);
+        }
+
+        async Task<SceneResult> TransitionWithIntermediateLoadingAsync(SceneParameters sceneParameters, ILoadSceneInfo intermediateSceneInfo, LoadingBehavior loadingBehavior, CancellationToken token)
+        {
+            LoadingProgress progress = loadingBehavior.Progress;
+            await progress.TransitionInTask.Task;
+            await UnloadSourceSceneAsync(token);
+
+            Scene[] loadedScenes = await LoadAsync(sceneParameters, progress, token);
+            progress.SetLoadingCompleted();
+
+            await progress.TransitionOutTask.Task;
+            await UnloadAsync(new SceneParameters(intermediateSceneInfo), token);
+            return new SceneResult(loadedScenes);
+        }
+
+        async Task<SceneResult> TransitionWithIntermediateNoLoadingAsync(SceneParameters sceneParameters, ILoadSceneInfo intermediateSceneInfo, CancellationToken token)
+        {
+            await UnloadSourceSceneAsync(token);
+            Scene[] loadedScenes = await LoadAsync(sceneParameters, token: token);
+            await UnloadAsync(new SceneParameters(intermediateSceneInfo), token);
+            return new SceneResult(loadedScenes);
+        }
+
+        async Task PollProgressAsync(ISceneData[] sceneDataArray, IProgress<float> progress, CancellationToken token = default)
+        {
+            bool isDone = false;
+            while (!isDone && !token.IsCancellationRequested)
+            {
+                await Task.Yield();
+                isDone = SceneDataUtilities.HasCompletedAllSceneLoadOperations(sceneDataArray);
+                progress?.Report(SceneDataUtilities.GetAverageSceneLoadOperationProgress(sceneDataArray));
+            }
+        }
+
+        Task<SceneResult> UnloadSourceSceneAsync(CancellationToken token)
+        {
+            Scene sourceScene = GetActiveScene();
+            if (!sourceScene.IsValid())
+                return Task.FromResult<SceneResult>(default);
+
+            return UnloadAsync(new SceneParameters(new LoadSceneInfoScene(sourceScene)), token);
         }
     }
 }

Runtime/AdvancedSceneManager.cs renamed to Runtime/CoreSceneManager.cs

@@ -1,3 +1,4 @@
+using System;
 using UnityEngine.SceneManagement;
 
 namespace MyGameDevTools.SceneLoading
@@ -7,6 +8,11 @@ namespace MyGameDevTools.SceneLoading
     /// </summary>
     public interface IAsyncSceneOperation
     {
+        /// <summary>
+        /// Event fired when the async operation is done.
+        /// </summary>
+        event Action Completed;
+
         /// <summary>
         /// Progress of the load/unload operation from 0 to 1 (float).
         /// </summary>

Runtime/AdvancedSceneManager.cs.meta renamed to Runtime/CoreSceneManager.cs.meta

@@ -37,6 +37,13 @@ public interface ISceneData
         /// </summary>
         void UpdateSceneReference();
 
+        /// <summary>
+        /// Returns whether this <see cref="ISceneData"/> can be matched by the given <paramref name="loadSceneInfo"/>.
+        /// If the <paramref name="loadSceneInfo"/> is equal to the <see cref="ISceneData.LoadSceneInfo"/> or has a direct reference to the scene, it returns true.
+        /// </summary>
+        /// <param name="loadSceneInfo"><see cref="ILoadSceneInfo"/> to validate a match.</param>
+        bool MatchesLoadSceneInfo(ILoadSceneInfo loadSceneInfo);
+
         /// <summary>
         /// Triggers the load async operation and updates the <see cref="AsyncOperation"/> reference.
         /// </summary>