Update addressable samples

Author: joaoborks

Editor/Authoring/MyUnityTools.SceneLoading.Authoring.asmdef

@@ -2,7 +2,9 @@
     "name": "MyUnityTools.SceneLoading.Authoring",
     "rootNamespace": "",
     "references": [],
-    "includePlatforms": [],
+    "includePlatforms": [
+        "Editor"
+    ],
     "excludePlatforms": [],
     "allowUnsafeCode": false,
     "overrideReferences": false,

Runtime/Interfaces/IAddressableLoadSceneInfo.cs

@@ -10,9 +10,21 @@
 
 namespace MyUnityTools.SceneLoading.AddressablesSupport
 {
+    /// <summary>
+    /// Interface to standardize addressable scene unload info.
+    /// Can be created with either the target scene's <see cref="AsyncOperationHandle{TObject}"/> (<see cref="AddressableLoadSceneInfoOperationHandle"/>),
+    /// the <see cref="SceneInstance"/> (<see cref="AddressableLoadSceneInfoInstance"/>) or its name (<see cref="AddressableLoadSceneInfoName"/>).
+    /// </summary>
     public interface IAddressableLoadSceneInfo
     {
-        AsyncOperationHandle<SceneInstance> UnloadSceneAsync(IAddressableSceneManager sceneManager);
+        /// <summary>
+        /// Unloads the provided scene asynchronously.
+        /// Internally calls <see cref="UnityEngine.AddressableAssets.Addressables.UnloadSceneAsync(AsyncOperationHandle, bool)"/>.
+        /// </summary>
+        /// <param name="sceneManager">The reference to the <see cref="IAddressableSceneManager"/> that keeps track of the active scenes.</param>
+        /// <param name="autoReleaseHandle">Should the <see cref="AsyncOperationHandle{TObject}"/> be released automatically?</param>
+        /// <returns>The unload <see cref="AsyncOperationHandle{TObject}"/>.</returns>
+        AsyncOperationHandle<SceneInstance> UnloadSceneAsync(IAddressableSceneManager sceneManager, bool autoReleaseHandle = true);
     }
 }
 #endif

Runtime/Interfaces/IAddressableLoadSceneReference.cs

@@ -5,23 +5,23 @@
  * Created on: 8/24/2022 (en-US)
  */
 
-using UnityEngine.AddressableAssets;
 using UnityEngine.ResourceManagement.AsyncOperations;
 using UnityEngine.ResourceManagement.ResourceProviders;
 using UnityEngine.SceneManagement;
 
 namespace MyUnityTools.SceneLoading.AddressablesSupport
 {
     /// <summary>
-    /// Interface to standardize addressable scene information.
-    /// Can be created with either the target scene's <see cref="AssetReference"/> (<see cref="AddressableLoadSceneReferenceAsset"/>) or the scene's runtime key (<see cref="AddressableLoadSceneReferenceKey"/>).
+    /// Interface to standardize addressable scene load reference.
+    /// Can be created with either the target scene's <see cref="UnityEngine.AddressableAssets.AssetReference"/> (<see cref="AddressableLoadSceneReferenceAsset"/>) or the scene's runtime key (<see cref="AddressableLoadSceneReferenceKey"/>).
     /// </summary>
     public interface IAddressableLoadSceneReference
     {
         /// <summary>
         /// Loads the provided scene asynchronously.
-        /// Internally calls <see cref="Addressables.LoadSceneAsync(object, LoadSceneMode, bool, int)"/>.
+        /// Internally calls <see cref="UnityEngine.AddressableAssets.Addressables.LoadSceneAsync(object, LoadSceneMode, bool, int)"/>.
         /// </summary>
+        /// <param name="sceneManager">The reference to the <see cref="IAddressableSceneManager"/> that keeps track of the active scenes.</param>
         /// <returns>The load <see cref="AsyncOperationHandle{TObject}"/>.</returns>
         AsyncOperationHandle<SceneInstance> LoadSceneAsync(IAddressableSceneManager sceneManager);
     }

Runtime/Interfaces/IAddressableSceneLoader.cs

@@ -7,15 +7,66 @@
 
 namespace MyUnityTools.SceneLoading.AddressablesSupport
 {
+    /// <summary>
+    /// Interface to standardize addressable scene operations.
+    /// </summary>
     public interface IAddressableSceneLoader
     {
+        /// <summary>
+        /// The addressable Scene Manager, responsible for keeping track of the loaded addressable scene stack.
+        /// </summary>
         IAddressableSceneManager SceneManager { get; }
 
+        /// <summary>
+        /// Triggers a scene transition.
+        /// It will transition from the current active scene (<see cref="IAddressableSceneManager.GetActiveSceneHandle"/>)
+        /// to the target scene (<paramref name="targetSceneReference"/>), with an optional intermediate loading scene (<paramref name="intermediateSceneReference"/>).
+        /// If the <paramref name="intermediateSceneReference"/> is not set, the transition will have no intermediate loading scene and will instead simply load the target scene directly.
+        /// The complete transition flow is:
+        /// <br/><br/>
+        /// 1. Load the intermediate scene (if provided).<br/>
+        /// 2. Load the target scene.<br/>
+        /// 3. Unload the intermediate scene (if provided).<br/>
+        /// 4. Unload the previous scene
+        /// </summary>
+        /// <param name="targetSceneReference">
+        /// The scene that's going to be transitioned to.
+        /// Can be the scene's addressable <see cref="UnityEngine.AddressableAssets.AssetReference"/> (<see cref="AddressableLoadSceneReferenceAsset"/>)
+        /// or runtime key (<see cref="AddressableLoadSceneReferenceKey"/>).
+        /// </param>
+        /// <param name="intermediateSceneReference">
+        /// The scene that's going to be loaded as the transition intermediate (as a loading scene).
+        /// Can be the scene's addressable <see cref="UnityEngine.AddressableAssets.AssetReference"/> (<see cref="AddressableLoadSceneReferenceAsset"/>)
+        /// or runtime key (<see cref="AddressableLoadSceneReferenceKey"/>).
+        /// If null, the transition will not have an intermediate loading scene.
+        /// </param>
         void TransitionToScene(IAddressableLoadSceneReference targetSceneReference, IAddressableLoadSceneReference intermediateSceneReference = null);
 
-        void LoadScene(IAddressableLoadSceneReference sceneReference, bool setActive = false); 
-        
+        /// <summary>
+        /// Unloads the given scene from the current scene stack.
+        /// </summary>
+        /// <param name="sceneInfo">
+        /// Target scene info.
+        /// Can be the scene's addressable <see cref="UnityEngine.ResourceManagement.AsyncOperations.AsyncOperationHandle{TObject}"/> (<see cref="AddressableLoadSceneInfoOperationHandle"/>),
+        /// its <see cref="UnityEngine.ResourceManagement.ResourceProviders.SceneInstance"/> (<see cref="AddressableLoadSceneInfoInstance"/>),
+        /// or its name (<see cref="AddressableLoadSceneInfoName"/>).
+        /// </param>
         void UnloadScene(IAddressableLoadSceneInfo sceneInfo);
+
+        /// <summary>
+        /// Loads a scene additively on top of the current scene stack, optionally marking it as the active scene
+        /// (<see cref="IAddressableSceneManager.SetActiveSceneHandle(UnityEngine.ResourceManagement.AsyncOperations.AsyncOperationHandle{UnityEngine.ResourceManagement.ResourceProviders.SceneInstance})"/>).
+        /// </summary>
+        /// <param name="sceneInfo">
+        /// The scene that's going to be loaded.
+        /// Can be the scene's addressable <see cref="UnityEngine.AddressableAssets.AssetReference"/> (<see cref="AddressableLoadSceneReferenceAsset"/>)
+        /// or runtime key (<see cref="AddressableLoadSceneReferenceKey"/>).
+        /// </param>
+        /// <param name="setActive">
+        /// Should the loaded scene be marked as active?
+        /// Equivalent to calling <see cref="IAddressableSceneManager.SetActiveSceneHandle(UnityEngine.ResourceManagement.AsyncOperations.AsyncOperationHandle{UnityEngine.ResourceManagement.ResourceProviders.SceneInstance})"/>.
+        /// </param>
+        void LoadScene(IAddressableLoadSceneReference sceneReference, bool setActive = false);
     }
 }
 #endif

Runtime/Interfaces/IAddressableSceneLoaderAsync.cs

@@ -10,12 +10,63 @@
 
 namespace MyUnityTools.SceneLoading.AddressablesSupport
 {
+    /// <summary>
+    /// Interface to standardize async addressable scene operations.
+    /// </summary>
     public interface IAddressableSceneLoaderAsync : IAddressableSceneLoader
     {
+        /// <summary>
+        /// Triggers a scene transition asynchronously.
+        /// It will transition from the current active scene (<see cref="IAddressableSceneManager.GetActiveSceneHandle"/>)
+        /// to the target scene (<paramref name="targetSceneReference"/>), with an optional intermediate loading scene (<paramref name="intermediateSceneReference"/>).
+        /// If the <paramref name="intermediateSceneReference"/> is not set, the transition will have no intermediate loading scene and will instead simply load the target scene directly.
+        /// The complete transition flow is:
+        /// <br/><br/>
+        /// 1. Load the intermediate scene (if provided).<br/>
+        /// 2. Load the target scene.<br/>
+        /// 3. Unload the intermediate scene (if provided).<br/>
+        /// 4. Unload the previous scene
+        /// </summary>
+        /// <param name="targetSceneReference">
+        /// The scene that's going to be transitioned to.
+        /// Can be the scene's addressable <see cref="UnityEngine.AddressableAssets.AssetReference"/> (<see cref="AddressableLoadSceneReferenceAsset"/>)
+        /// or runtime key (<see cref="AddressableLoadSceneReferenceKey"/>).
+        /// </param>
+        /// <param name="intermediateSceneReference">
+        /// The scene that's going to be loaded as the transition intermediate (as a loading scene).
+        /// Can be the scene's addressable <see cref="UnityEngine.AddressableAssets.AssetReference"/> (<see cref="AddressableLoadSceneReferenceAsset"/>)
+        /// or runtime key (<see cref="AddressableLoadSceneReferenceKey"/>).
+        /// If null, the transition will not have an intermediate loading scene.
+        /// </param>
+        /// <returns>The transition awaitable <see cref="Task{TResult}"/>"/> with the resulting <see cref="SceneInstance"/>.</returns>
         Task<SceneInstance> TransitionToSceneAsync(IAddressableLoadSceneReference targetSceneReference, IAddressableLoadSceneReference intermediateSceneReference = null);
 
+        /// <summary>
+        /// Loads a scene additively asynchronously on top of the current scene stack, optionally marking it as the active scene
+        /// (<see cref="IAddressableSceneManager.SetActiveSceneHandle(UnityEngine.ResourceManagement.AsyncOperations.AsyncOperationHandle{UnityEngine.ResourceManagement.ResourceProviders.SceneInstance})"/>).
+        /// </summary>
+        /// <param name="sceneInfo">
+        /// The scene that's going to be loaded.
+        /// Can be the scene's addressable <see cref="UnityEngine.AddressableAssets.AssetReference"/> (<see cref="AddressableLoadSceneReferenceAsset"/>)
+        /// or runtime key (<see cref="AddressableLoadSceneReferenceKey"/>).
+        /// </param>
+        /// <param name="setActive">
+        /// Should the loaded scene be marked as active?
+        /// Equivalent to calling <see cref="IAddressableSceneManager.SetActiveSceneHandle(UnityEngine.ResourceManagement.AsyncOperations.AsyncOperationHandle{UnityEngine.ResourceManagement.ResourceProviders.SceneInstance})"/>.
+        /// </param>
+        /// <returns>The load awaitable <see cref="Task{TResult}"/>"/> with the resulting <see cref="SceneInstance"/>.</returns>
         Task<SceneInstance> LoadSceneAsync(IAddressableLoadSceneReference sceneReference, bool setActive = false);
 
+        /// <summary>
+        /// Unloads the given scene asynchronously from the current scene stack.
+        /// </summary>
+        /// <param name="sceneInfo">
+        /// Target scene info.
+        /// Can be the scene's addressable <see cref="UnityEngine.ResourceManagement.AsyncOperations.AsyncOperationHandle{TObject}"/> (<see cref="AddressableLoadSceneInfoOperationHandle"/>),
+        /// its <see cref="UnityEngine.ResourceManagement.ResourceProviders.SceneInstance"/> (<see cref="AddressableLoadSceneInfoInstance"/>),
+        /// or its name (<see cref="AddressableLoadSceneInfoName"/>).
+        /// </param>
+        /// <returns>The unload awaitable <see cref="Task"/>.</returns>
         Task UnloadSceneAsync(IAddressableLoadSceneInfo sceneInfo);
     }
 }

Runtime/Interfaces/IAddressableSceneLoaderUniTask.cs

@@ -10,12 +10,63 @@
 
 namespace MyUnityTools.SceneLoading.AddressablesSupport.UniTaskSupport
 {
+    /// <summary>
+    /// Interface to standardize async addressable scene operations with <see cref="UniTask"/>.
+    /// </summary>
     public interface IAddressableSceneLoaderUniTask : IAddressableSceneLoader
     {
+        /// <summary>
+        /// Triggers a scene transition asynchronously.
+        /// It will transition from the current active scene (<see cref="IAddressableSceneManager.GetActiveSceneHandle"/>)
+        /// to the target scene (<paramref name="targetSceneReference"/>), with an optional intermediate loading scene (<paramref name="intermediateSceneReference"/>).
+        /// If the <paramref name="intermediateSceneReference"/> is not set, the transition will have no intermediate loading scene and will instead simply load the target scene directly.
+        /// The complete transition flow is:
+        /// <br/><br/>
+        /// 1. Load the intermediate scene (if provided).<br/>
+        /// 2. Load the target scene.<br/>
+        /// 3. Unload the intermediate scene (if provided).<br/>
+        /// 4. Unload the previous scene
+        /// </summary>
+        /// <param name="targetSceneReference">
+        /// The scene that's going to be transitioned to.
+        /// Can be the scene's addressable <see cref="UnityEngine.AddressableAssets.AssetReference"/> (<see cref="AddressableLoadSceneReferenceAsset"/>)
+        /// or runtime key (<see cref="AddressableLoadSceneReferenceKey"/>).
+        /// </param>
+        /// <param name="intermediateSceneReference">
+        /// The scene that's going to be loaded as the transition intermediate (as a loading scene).
+        /// Can be the scene's addressable <see cref="UnityEngine.AddressableAssets.AssetReference"/> (<see cref="AddressableLoadSceneReferenceAsset"/>)
+        /// or runtime key (<see cref="AddressableLoadSceneReferenceKey"/>).
+        /// If null, the transition will not have an intermediate loading scene.
+        /// </param>
+        /// <returns>The transition awaitable <see cref="UniTask{TResult}"/>"/> with the resulting <see cref="SceneInstance"/>.</returns>
         UniTask<SceneInstance> TransitionToSceneAsync(IAddressableLoadSceneReference targetSceneReference, IAddressableLoadSceneReference intermediateSceneReference = null);
 
+        /// <summary>
+        /// Loads a scene additively asynchronously on top of the current scene stack, optionally marking it as the active scene
+        /// (<see cref="IAddressableSceneManager.SetActiveSceneHandle(UnityEngine.ResourceManagement.AsyncOperations.AsyncOperationHandle{UnityEngine.ResourceManagement.ResourceProviders.SceneInstance})"/>).
+        /// </summary>
+        /// <param name="sceneInfo">
+        /// The scene that's going to be loaded.
+        /// Can be the scene's addressable <see cref="UnityEngine.AddressableAssets.AssetReference"/> (<see cref="AddressableLoadSceneReferenceAsset"/>)
+        /// or runtime key (<see cref="AddressableLoadSceneReferenceKey"/>).
+        /// </param>
+        /// <param name="setActive">
+        /// Should the loaded scene be marked as active?
+        /// Equivalent to calling <see cref="IAddressableSceneManager.SetActiveSceneHandle(UnityEngine.ResourceManagement.AsyncOperations.AsyncOperationHandle{UnityEngine.ResourceManagement.ResourceProviders.SceneInstance})"/>.
+        /// </param>
+        /// <returns>The load awaitable <see cref="UniTask{TResult}"/>"/> with the resulting <see cref="SceneInstance"/>.</returns>
         UniTask<SceneInstance> LoadSceneAsync(IAddressableLoadSceneReference sceneReference, bool setActive = false);
 
+        /// <summary>
+        /// Unloads the given scene asynchronously from the current scene stack.
+        /// </summary>
+        /// <param name="sceneInfo">
+        /// Target scene info.
+        /// Can be the scene's addressable <see cref="UnityEngine.ResourceManagement.AsyncOperations.AsyncOperationHandle{TObject}"/> (<see cref="AddressableLoadSceneInfoOperationHandle"/>),
+        /// its <see cref="UnityEngine.ResourceManagement.ResourceProviders.SceneInstance"/> (<see cref="AddressableLoadSceneInfoInstance"/>),
+        /// or its name (<see cref="AddressableLoadSceneInfoName"/>).
+        /// </param>
+        /// <returns>The unload awaitable <see cref="UniTask"/>.</returns>
         UniTask UnloadSceneAsync(IAddressableLoadSceneInfo sceneInfo);
     }
 }