Merge pull request #14 from mygamedevtools/feature/hybrid-transitions

[Feature] Add transitions from external scenes

Author: joaoborks

Packages/mygamedevtools-scene-loader/Runtime/Interfaces/ISceneLoader.cs

@@ -4,6 +4,8 @@
  * Created on: 7/16/2022 (en-US)
  */
 
+using UnityEngine.SceneManagement;
+
 namespace MyGameDevTools.SceneLoading
 {
     /// <summary>
@@ -22,6 +24,8 @@ public interface ISceneLoader
         /// It will transition from the current active scene (<see cref="ISceneManager.GetActiveScene()"/>)
         /// to the target scene (<paramref name="targetSceneInfo"/>), with an optional intermediate loading scene (<paramref name="intermediateSceneInfo"/>).
         /// If the <paramref name="intermediateSceneInfo"/> is not set, the transition will have no intermediate loading scene and will instead simply load the target scene directly.
+        /// Also, you can provide a scene that wasn't loaded from this scene loader to transition from, as the <paramref name="externalOriginScene"/>,
+        /// instead of transitioning from the current active scene.
         /// The complete transition flow is:
         /// <br/><br/>
         /// 1. Load the intermediate scene (if provided).<br/>
@@ -36,7 +40,10 @@ public interface ISceneLoader
         /// A reference to the scene that's going to be loaded as the transition intermediate (as a loading scene).
         /// If null, the transition will not have an intermediate loading scene.
         /// </param>
-        void TransitionToScene(ILoadSceneInfo targetSceneInfo, ILoadSceneInfo intermediateSceneInfo = null);
+        /// <param name="externalOriginScene">
+        /// A reference to a scene loaded outside of this scene loader, instead of taking the current active scene as the origin scene.
+        /// </param>
+        void TransitionToScene(ILoadSceneInfo targetSceneInfo, ILoadSceneInfo intermediateSceneInfo = null, Scene externalOriginScene = default);
 
         /// <summary>
         /// Unloads the given scene from the current scene stack.
@@ -48,12 +55,12 @@ public interface ISceneLoader
 
         /// <summary>
         /// Loads a scene additively on top of the current scene stack, optionally marking it as the active scene
-        /// (<see cref="ISceneManager.SetActiveScene(UnityEngine.SceneManagement.Scene)"/>).
+        /// (<see cref="ISceneManager.SetActiveScene(Scene)"/>).
         /// </summary>
         /// <param name="sceneInfo">
         /// Reference to the scene that's going to be loaded.
         /// </param>
-        /// <param name="setActive">Should the loaded scene be marked as active? Equivalent to calling <see cref="ISceneManager.SetActiveScene(UnityEngine.SceneManagement.Scene)"/>.</param>
+        /// <param name="setActive">Should the loaded scene be marked as active? Equivalent to calling <see cref="ISceneManager.SetActiveScene(Scene)"/>.</param>
         void LoadScene(ILoadSceneInfo sceneInfo, bool setActive = false);
     }
 }

Packages/mygamedevtools-scene-loader/Runtime/Interfaces/ISceneLoaderAsync.cs

@@ -5,18 +5,19 @@
  */
 
 using System;
+using UnityEngine.SceneManagement;
 
 namespace MyGameDevTools.SceneLoading
 {
     /// <summary>
     /// Interface to standardize async scene loading operations.
-    /// <typeparamref name="TAsync"/> can be a <see cref="UnityEngine.Coroutine"/> or an awaitable type that returns <see cref="UnityEngine.SceneManagement.Scene"/>, such as
+    /// <typeparamref name="TAsync"/> can be a <see cref="UnityEngine.Coroutine"/> or an awaitable type that returns <see cref="Scene"/>, such as
     /// <see cref="System.Threading.Tasks.ValueTask{T}"/>.
     /// </summary>
     public interface ISceneLoaderAsync<TAsync> : ISceneLoader
     {
         /// <summary>
-        /// Async version of the <see cref="ISceneLoader.TransitionToScene(ILoadSceneInfo, ILoadSceneInfo)"/>.
+        /// Async version of the <see cref="ISceneLoader.TransitionToScene(ILoadSceneInfo, ILoadSceneInfo, Scene)"/>.
         /// </summary>
         /// <param name="targetSceneReference">
         /// A reference to the scene that's going to be transitioned to.
@@ -25,10 +26,13 @@ public interface ISceneLoaderAsync<TAsync> : ISceneLoader
         /// A reference to the scene that's going to be loaded as the transition intermediate (as a loading scene).
         /// If null, the transition will not have an intermediate loading scene.
         /// </param>
+        /// <param name="externalOriginScene">
+        /// A reference to a scene loaded outside of this scene loader, instead of taking the current active scene as the origin scene.
+        /// </param>
         /// <returns>
         /// The loading operation.
         /// </returns>
-        TAsync TransitionToSceneAsync(ILoadSceneInfo targetSceneReference, ILoadSceneInfo intermediateSceneReference = default);
+        TAsync TransitionToSceneAsync(ILoadSceneInfo targetSceneReference, ILoadSceneInfo intermediateSceneReference = default, Scene externalOriginScene = default);
 
         /// <summary>
         /// Async version of the <see cref="ISceneLoader.LoadScene(ILoadSceneInfo, bool)"/>.
@@ -37,7 +41,7 @@ public interface ISceneLoaderAsync<TAsync> : ISceneLoader
         /// Reference to the scene that's going to be loaded.
         /// </param>
         /// <param name="setActive">
-        /// Should the loaded scene be marked as active? Equivalent to calling <see cref="ISceneManager.SetActiveScene(UnityEngine.SceneManagement.Scene)"/>.
+        /// Should the loaded scene be marked as active? Equivalent to calling <see cref="ISceneManager.SetActiveScene(Scene)"/>.
         /// </param>
         /// <param name="progress">
         /// Optional <see cref="IProgress{T}"/> reference to report the scene loading progress (ranging from 0 to 1).

Packages/mygamedevtools-scene-loader/Runtime/SceneLoaders/SceneLoaderAsync.cs

@@ -22,59 +22,77 @@ public SceneLoaderAsync(ISceneManager manager)
             _manager = manager ?? throw new ArgumentNullException("Cannot create a scene loader with a null Scene Manager");
         }
 
-        public void TransitionToScene(ILoadSceneInfo targetSceneInfo, ILoadSceneInfo intermediateSceneInfo) => TransitionToSceneAsync(targetSceneInfo, intermediateSceneInfo);
+        public void TransitionToScene(ILoadSceneInfo targetSceneInfo, ILoadSceneInfo intermediateSceneInfo, Scene externalOriginScene) => TransitionToSceneAsync(targetSceneInfo, intermediateSceneInfo, externalOriginScene);
 
         public void UnloadScene(ILoadSceneInfo sceneInfo) => _ = UnloadSceneAsync(sceneInfo);
 
         public void LoadScene(ILoadSceneInfo sceneInfo, bool setActive) => _ = LoadSceneAsync(sceneInfo, setActive);
 
-        public ValueTask<Scene> TransitionToSceneAsync(ILoadSceneInfo targetSceneInfo, ILoadSceneInfo intermediateSceneInfo) => intermediateSceneInfo == null ? TransitionDirectlyAsync(targetSceneInfo) : TransitionWithIntermediateAsync(targetSceneInfo, intermediateSceneInfo);
+        public ValueTask<Scene> TransitionToSceneAsync(ILoadSceneInfo targetSceneInfo, ILoadSceneInfo intermediateSceneInfo, Scene externalOriginScene) => intermediateSceneInfo == null ? TransitionDirectlyAsync(targetSceneInfo, externalOriginScene) : TransitionWithIntermediateAsync(targetSceneInfo, intermediateSceneInfo, externalOriginScene);
 
         public ValueTask<Scene> LoadSceneAsync(ILoadSceneInfo sceneInfo, bool setActive = false, IProgress<float> progress = null) => _manager.LoadSceneAsync(sceneInfo, setActive, progress);
 
         public ValueTask<Scene> UnloadSceneAsync(ILoadSceneInfo sceneInfo) => _manager.UnloadSceneAsync(sceneInfo);
 
-        async ValueTask<Scene> TransitionWithIntermediateAsync(ILoadSceneInfo targetSceneInfo, ILoadSceneInfo intermediateSceneInfo)
+        async ValueTask<Scene> TransitionDirectlyAsync(ILoadSceneInfo loadSceneInfo, Scene externalOriginScene)
         {
-            var currentScene = _manager.GetActiveScene();
+            var externalOrigin = externalOriginScene.IsValid();
+            var currentScene = externalOrigin ? externalOriginScene : _manager.GetActiveScene();
+            await UnloadCurrentScene(currentScene, externalOrigin);
+            return await LoadSceneAsync(loadSceneInfo, true);
+        }
+
+        async ValueTask<Scene> TransitionWithIntermediateAsync(ILoadSceneInfo targetSceneInfo, ILoadSceneInfo intermediateSceneInfo, Scene externalOriginScene)
+        {
+            var externalOrigin = externalOriginScene.IsValid();
+            var currentScene = externalOrigin ? externalOriginScene : _manager.GetActiveScene();
             await _manager.LoadSceneAsync(intermediateSceneInfo);
 
             var loadingBehavior = Object.FindObjectOfType<LoadingBehavior>();
-            Scene loadedScene;
-            if (loadingBehavior)
-            {
-                var progress = loadingBehavior.Progress;
-                while (progress.State != LoadingState.Loading)
-                    await Task.Yield();
+            return loadingBehavior
+                ? await TransitionWithIntermediateLoadingAsync(targetSceneInfo, intermediateSceneInfo, loadingBehavior, currentScene, externalOrigin)
+                : await TransitionWithIntermediateNoLoadingAsync(targetSceneInfo, intermediateSceneInfo, currentScene, externalOrigin);
+        }
 
-                if (currentScene.IsValid())
-                    await UnloadSceneAsync(new LoadSceneInfoScene(currentScene));
+        async ValueTask<Scene> TransitionWithIntermediateLoadingAsync(ILoadSceneInfo targetSceneInfo, ILoadSceneInfo intermediateSceneInfo, LoadingBehavior loadingBehavior, Scene currentScene, bool externalOrigin)
+        {
+            var progress = loadingBehavior.Progress;
+            while (progress.State != LoadingState.Loading)
+                await Task.Yield();
 
-                loadedScene = await _manager.LoadSceneAsync(targetSceneInfo, true, progress);
-                progress.SetState(LoadingState.TargetSceneLoaded);
+            await UnloadCurrentScene(currentScene, externalOrigin);
 
-                while (progress.State != LoadingState.TransitionComplete)
-                    await Task.Yield();
+            var loadedScene = await _manager.LoadSceneAsync(targetSceneInfo, true, progress);
+            progress.SetState(LoadingState.TargetSceneLoaded);
 
-                _ = UnloadSceneAsync(intermediateSceneInfo);
-            }
-            else
-            {
-                if (currentScene.IsValid())
-                    await UnloadSceneAsync(new LoadSceneInfoScene(currentScene));
-                loadedScene = await LoadSceneAsync(targetSceneInfo, true);
-                _ = UnloadSceneAsync(intermediateSceneInfo);
-            }
+            while (progress.State != LoadingState.TransitionComplete)
+                await Task.Yield();
 
+            _ = UnloadSceneAsync(intermediateSceneInfo);
             return loadedScene;
         }
 
-        async ValueTask<Scene> TransitionDirectlyAsync(ILoadSceneInfo loadSceneInfo)
+        async ValueTask<Scene> TransitionWithIntermediateNoLoadingAsync(ILoadSceneInfo targetSceneInfo, ILoadSceneInfo intermediateSceneInfo, Scene currentScene, bool externalOrigin)
         {
-            var currentScene = _manager.GetActiveScene();
-            if (currentScene.IsValid())
-                await UnloadSceneAsync(new LoadSceneInfoScene(currentScene));
-            return await LoadSceneAsync(loadSceneInfo, true);
+            await UnloadCurrentScene(currentScene, externalOrigin);
+            var loadedScene = await LoadSceneAsync(targetSceneInfo, true);
+            _ = UnloadSceneAsync(intermediateSceneInfo);
+            return loadedScene;
+        }
+
+        async ValueTask UnloadCurrentScene(Scene currentScene, bool externalOrigin)
+        {
+            if (!currentScene.IsValid())
+                return;
+
+            if (externalOrigin)
+            {
+                var operation = UnityEngine.SceneManagement.SceneManager.UnloadSceneAsync(currentScene);
+                while (!operation.isDone)
+                    await Task.Yield();
+            }
+            else
+                await _manager.UnloadSceneAsync(new LoadSceneInfoScene(currentScene));
         }
     }
 }

Packages/mygamedevtools-scene-loader/Runtime/SceneLoaders/SceneLoaderCoroutine.cs

@@ -4,9 +4,11 @@
  * Created on: 9/4/2022 (en-US)
  */
 
+using Cysharp.Threading.Tasks;
 using System;
 using System.Collections;
 using UnityEngine;
+using UnityEngine.SceneManagement;
 using Object = UnityEngine.Object;
 
 namespace MyGameDevTools.SceneLoading
@@ -22,13 +24,13 @@ public SceneLoaderCoroutine(ISceneManager manager)
             _manager = manager ?? throw new ArgumentNullException("Cannot create a scene loader with a null Scene Manager");
         }
 
-        public void TransitionToScene(ILoadSceneInfo targetSceneInfo, ILoadSceneInfo intermediateSceneInfo) => TransitionToSceneAsync(targetSceneInfo, intermediateSceneInfo);
+        public void TransitionToScene(ILoadSceneInfo targetSceneInfo, ILoadSceneInfo intermediateSceneInfo, Scene externalOriginScene) => TransitionToSceneAsync(targetSceneInfo, intermediateSceneInfo, externalOriginScene);
 
         public void UnloadScene(ILoadSceneInfo sceneInfo) => UnloadSceneAsync(sceneInfo);
 
         public void LoadScene(ILoadSceneInfo sceneInfo, bool setActive) => LoadSceneAsync(sceneInfo, setActive);
 
-        public Coroutine TransitionToSceneAsync(ILoadSceneInfo targetSceneInfo, ILoadSceneInfo intermediateSceneInfo) => RoutineBehaviour.Instance.StartCoroutine(intermediateSceneInfo == null ? TransitionDirectlyRoutine(targetSceneInfo) : TransitionWithIntermediateRoutine(targetSceneInfo, intermediateSceneInfo));
+        public Coroutine TransitionToSceneAsync(ILoadSceneInfo targetSceneInfo, ILoadSceneInfo intermediateSceneInfo, Scene externalOriginScene) => RoutineBehaviour.Instance.StartCoroutine(intermediateSceneInfo == null ? TransitionDirectlyRoutine(targetSceneInfo, externalOriginScene) : TransitionWithIntermediateRoutine(targetSceneInfo, intermediateSceneInfo, externalOriginScene));
 
         public Coroutine UnloadSceneAsync(ILoadSceneInfo sceneInfo) => RoutineBehaviour.Instance.StartCoroutine(UnloadRoutine(sceneInfo));
 
@@ -44,42 +46,57 @@ IEnumerator UnloadRoutine(ILoadSceneInfo sceneInfo)
             yield return new WaitTask(_manager.UnloadSceneAsync(sceneInfo).AsTask());
         }
 
-        IEnumerator TransitionWithIntermediateRoutine(ILoadSceneInfo targetSceneInfo, ILoadSceneInfo intermediateSceneInfo)
+        IEnumerator TransitionDirectlyRoutine(ILoadSceneInfo targetSceneInfo, Scene externalOriginScene)
         {
-            var currentScene = _manager.GetActiveScene();
+            var externalOrigin = externalOriginScene.IsValid();
+            var currentScene = externalOrigin ? externalOriginScene : _manager.GetActiveScene();
+            yield return UnloadCurrentScene(currentScene, externalOrigin);
+            yield return LoadRoutine(targetSceneInfo, true, null);
+        }
+
+        IEnumerator TransitionWithIntermediateRoutine(ILoadSceneInfo targetSceneInfo, ILoadSceneInfo intermediateSceneInfo, Scene externalOriginScene)
+        {
+            var externalOrigin = externalOriginScene.IsValid();
+            var currentScene = externalOrigin ? externalOriginScene : _manager.GetActiveScene();
             yield return new WaitTask(_manager.LoadSceneAsync(intermediateSceneInfo).AsTask());
 
             var loadingBehavior = Object.FindObjectOfType<LoadingBehavior>();
-            if (loadingBehavior)
-            {
-                var progress = loadingBehavior.Progress;
-                yield return new WaitUntil(() => progress.State == LoadingState.Loading);
+            yield return loadingBehavior
+                ? TransitionWithIntermediateLoadingAsync(targetSceneInfo, intermediateSceneInfo, loadingBehavior, currentScene, externalOrigin)
+                : TransitionWithIntermediateNoLoadingAsync(targetSceneInfo, intermediateSceneInfo, currentScene, externalOrigin);
+        }
+
+        IEnumerator TransitionWithIntermediateLoadingAsync(ILoadSceneInfo targetSceneInfo, ILoadSceneInfo intermediateSceneInfo, LoadingBehavior loadingBehavior, Scene currentScene, bool externalOrigin)
+        {
+            var progress = loadingBehavior.Progress;
+            yield return new WaitUntil(() => progress.State == LoadingState.Loading);
 
-                if (currentScene.IsValid())
-                    yield return UnloadRoutine(new LoadSceneInfoScene(currentScene));
+            yield return UnloadCurrentScene(currentScene, externalOrigin);
 
-                yield return new WaitTask(_manager.LoadSceneAsync(targetSceneInfo, true, progress).AsTask());
-                progress.SetState(LoadingState.TargetSceneLoaded);
+            yield return new WaitTask(_manager.LoadSceneAsync(targetSceneInfo, true, progress).AsTask());
+            progress.SetState(LoadingState.TargetSceneLoaded);
 
-                yield return new WaitUntil(() => progress.State == LoadingState.TransitionComplete);
+            yield return new WaitUntil(() => progress.State == LoadingState.TransitionComplete);
 
-                UnloadSceneAsync(intermediateSceneInfo);
-            }
-            else
-            {
-                if (currentScene.IsValid())
-                    yield return UnloadRoutine(new LoadSceneInfoScene(currentScene));
-                yield return LoadRoutine(targetSceneInfo, true, null);
-                UnloadSceneAsync(intermediateSceneInfo);
-            }
+            UnloadSceneAsync(intermediateSceneInfo);
         }
 
-        IEnumerator TransitionDirectlyRoutine(ILoadSceneInfo targetSceneInfo)
+        IEnumerator TransitionWithIntermediateNoLoadingAsync(ILoadSceneInfo targetSceneInfo, ILoadSceneInfo intermediateSceneInfo, Scene currentScene, bool externalOrigin)
         {
-            var currentScene = _manager.GetActiveScene();
-            if (currentScene.IsValid())
-                yield return UnloadRoutine(new LoadSceneInfoScene(currentScene));
+            yield return UnloadCurrentScene(currentScene, externalOrigin);
             yield return LoadRoutine(targetSceneInfo, true, null);
+            UnloadSceneAsync(intermediateSceneInfo);
+        }
+
+        IEnumerator UnloadCurrentScene(Scene currentScene, bool externalOrigin)
+        {
+            if (!currentScene.IsValid())
+                yield break;
+
+            if (externalOrigin)
+                yield return UnityEngine.SceneManagement.SceneManager.UnloadSceneAsync(currentScene);
+            else
+                yield return UnloadRoutine(new LoadSceneInfoScene(currentScene));
         }
     }
 }