UPM release 3.0.0

CHANGELOG.md

@@ -19,6 +19,69 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 
 
+## [3.0.0] - 2023-07-07
+
+This release introduces support for addressable scenes.
+
+There are breaking changes to settings. Please visit the settings page and re-apply all your settings as soon as you update.
+
+### Breaking Changes
+- `SceneGuidToPathMapGenerator` is renamed to `SceneDataMapsGenerator`.
+- `SceneGuidToPathMapGenerationTriggers` is renamed to `SceneDataMapsGeneratorTriggers`.
+- Settings changes:
+  - Scene GUID to Path Map (new name Scene Data Maps) category:
+    - The category is renamed from `SceneGuidToPathMap` to `SceneDataMaps`.
+    - Key of the `GenerationTriggers` setting is changed from `SceneGuidToPathMap.GenerationTriggers` to `SceneDataMaps.GenerationTriggers`.
+    - Key of the `JsonFormatting` setting is changed from `SceneGuidToPathMap.JsonFormatting` to `SceneDataMaps.JsonFormatting`.
+    - Key of the `FailBuildIfGenerationFails` setting is changed from `SceneGuidToPathMap.FailBuildIfGenerationFails` to `SceneDataMaps.FailBuildIfGenerationFails`.
+  - Property Drawer category:
+    - `ShowInlineSceneInBuildUtility` setting is renamed to `ShowInlineToolbox`. The key is also changed from `PropertyDrawer.ShowInlineSceneInBuildUtility` to `PropertyDrawer.ShowInlineToolbox`.
+- All exceptions are moved from the `Eflatun.SceneReference` namespace to the new `Eflatun.SceneReference.Exceptions` namespace.
+- Following valiation properties are removed from `SceneReference`. They are instead replaced with a more informative `State` property. See the _Added_ section.
+  - `IsInSceneGuidToPathMap`: removed.
+  - `IsInBuildAndEnabled`: removed.
+  - `IsSafeToUse`: removed.
+  - `HasValue`: no longer public.
+- `SceneReferenceOptionsAttribute` changes:
+  - `Coloring` field is renamed to `SceneInBuildColoring`. It still controls the same cases of coloring, but they are no longer all the coloring options. See the _Changes_ section.
+  - `UtilityLine` field is removed. Its replacement is the `Toolbox` field. See the _Added_ section.
+
+### Added
+- `SceneDataMapsGenerator` now also generates a scene GUID to address map. The map will be empty if addressables support is disabled.
+- New map generation triggers:
+  - `AfterPackagesResolve`: Triggers after packages are resolved.
+  - `AfterAddressablesChange`: Triggers after addressable groups change.
+- Property drawer can optionally color addressables scenes differently to draw attention to them.
+- New inline utilties:
+  - `Make Addressable`: Makes the scene addressable.
+- New settings:
+  - Addressables Support (`AddressablesSupport`) category:
+    - `ColorAddressableScenes` setting: If enabled, scene references that have an addressable scene will be colored differently.
+    - An info box that displays the current addressables support status.
+- New exceptions:
+  - `AddressNotFoundException`
+  - `AddressNotUniqueException`
+  - `AddressablesSupportDisabledException`
+  - `SceneNotAddressableException`
+- `SceneGuidToAddressMapProvider` class: Provides a map of scene GUIDs to their address. Very similar to `SceneGuidToPathMapProvider`, with the exception that it cannot provide an inverse map. This is because the address of an asset is not guaranteed to be unique. Instead, it provides `GetGuidFromAddress` and `TryGetGuidFromAddress` methods.
+- `SceneReference.FromAddress` factory method: Creates a `SceneReference` from the given address.
+- `SceneReference.Address` property.
+- `SceneReference.State` property: This property replaces all previously exposed validation methods. It returns a `SceneReferenceState` enum, which describes the state of the `SceneReference` in terms of usage.
+- `SceneReferenceState` enum: Describes the state of the `SceneReference` in terms of usage.
+  - `Unsafe`: The `SceneReference` is not safe to use.
+  - `Regular`: The `SceneReference` is safe to use, and it references a regular scene.
+  - `Addressable`: The `SceneReference` is safe to use, and it references an addressable scene. This state is only possible if addressables support is enabled.
+- `SceneReferenceOptionsAttribute` new fields:
+  - `Toolbox`: Controls the visibility of the toolbox button. It replaces the now deleted `UtilityLine` field.
+  - `AddressableColoring`: Controls the coloring behaviour of the addressable scenes.
+- `ToolboxBehaviour` enum. Replaces the now deleted `UtilityLineBehaviour` enum with the same semantics.
+
+### Changed
+- The concept of Utility Line is replaced with the concept of Toolbox. In summary, instead of drawing buttons as a second line below the field, we instead draw a small button to the end of the field on the same line. When clicked, a toolbox popup appears with all the utilities.
+- `SceneInBuildColoring` argument (previously named `Coloring`) of `SceneReferenceOptionsAttribute` still controls the same types of coloring cases, but since they used to be all the cases, the field was implicitly controlling the entire coloring behaviour. While its semantics are not changed, since there are now other coloring cases, it is no longer the only field that controls the entire coloring behaviour.
+
+
+
 ## [2.1.0] - 2023-03-01
 
 ### Added
@@ -52,6 +115,7 @@ We renamed some of our internal serialized fields. Since we utilize `FormerlySer
 - Internal serialized field name changes:
 	- `SceneReference.sceneAsset` to `SceneReference.asset`
 	- `SceneReference.sceneAssetGuidHex` to `SceneReference.guid`
+- Menu item `Tools/Eflatun/Scene Reference/Run Scene GUID to Path Map Generator` is renamed to `Tools/Eflatun/Scene Reference/Generate Scene Data Maps`.
 
 ### Fixed
 - Prevent empty scene GUID hex in Unity serialized `SceneReference` instances.

Editor/Eflatun.SceneReference.Editor.asmdef

@@ -3,7 +3,9 @@
     "rootNamespace": "Eflatun.SceneReference.Editor",
     "references": [
         "GUID:caca889fed6088d40b22c2d7e2909c31",
-        "GUID:49818357e697641afb75d2f8acaf1861"
+        "GUID:49818357e697641afb75d2f8acaf1861",
+        "GUID:9e24947de15b9834991c9d8411ea37cf",
+        "GUID:69448af7b92c7f342b298e06a37122aa"
     ],
     "includePlatforms": [
         "Editor"
@@ -14,6 +16,17 @@
     "precompiledReferences": [],
     "autoReferenced": true,
     "defineConstraints": [],
-    "versionDefines": [],
+    "versionDefines": [
+        {
+            "name": "com.unity.addressables",
+            "expression": "",
+            "define": "ESR_ADDRESSABLES"
+        },
+        {
+            "name": "com.unity.addressables",
+            "expression": "[1.0.0,2.0.0)",
+            "define": "ESR_ADDRESSABLES_1_X_X"
+        }
+    ],
     "noEngineReferences": false
-}
+}

Editor/MapGeneratorTriggers/AddressablesChangeListener.cs

@@ -0,0 +1,38 @@
+#if ESR_ADDRESSABLES
+
+using UnityEditor;
+using UnityEditor.AddressableAssets;
+using UnityEditor.AddressableAssets.Settings;
+
+namespace Eflatun.SceneReference.Editor.MapGeneratorTriggers
+{
+    [InitializeOnLoad]
+    internal class AddressablesChangeListener
+    {
+        static AddressablesChangeListener()
+        {
+            AddressableAssetSettingsDefaultObject.Settings.OnModification += OnAddressablesChange;
+        }
+
+        private static void OnAddressablesChange(AddressableAssetSettings s, AddressableAssetSettings.ModificationEvent e, object o)
+        {
+            if (e == AddressableAssetSettings.ModificationEvent.EntryAdded ||
+                e == AddressableAssetSettings.ModificationEvent.EntryRemoved ||
+                e == AddressableAssetSettings.ModificationEvent.EntryModified ||
+                e == AddressableAssetSettings.ModificationEvent.EntryMoved ||
+                e == AddressableAssetSettings.ModificationEvent.EntryCreated)
+            {
+                if (SettingsManager.SceneDataMaps.IsGenerationTriggerEnabled(SceneDataMapsGeneratorTriggers.AfterAddressablesChange))
+                {
+                    SceneDataMapsGenerator.Run();
+                }
+                else
+                {
+                    Logger.Warn($"Skipping scene data maps generation after addressables changes. It is recommended to enable map generation after addressables changes, as an outdated map can result in broken scene references in runtime. You can enable it in {SettingsManager.SettingsMenuPathForDisplay}.");
+                }
+            }
+        }
+    }
+}
+
+#endif // ESR_ADDRESSABLES

Editor/MapGeneratorTriggers/BuildPreProcessor.cs

@@ -10,28 +10,28 @@ internal class BuildPreProcessor : IPreprocessBuildWithReport
 
         public void OnPreprocessBuild(BuildReport report)
         {
-            if (!SettingsManager.SceneGuidToPathMap.IsGenerationTriggerEnabled(SceneGuidToPathMapGenerationTriggers.BeforeBuild))
+            if (!SettingsManager.SceneDataMaps.IsGenerationTriggerEnabled(SceneDataMapsGeneratorTriggers.BeforeBuild))
             {
-                Logger.Warn($"Skipping scene GUID to path map generation before build. It is recommended to enable map generation before build, as an outdated map can result in broken scene references in runtime. You can enable it in {SettingsManager.SettingsMenuPathForDisplay}.");
+                Logger.Warn($"Skipping scene data maps generation before build. It is recommended to enable map generation before build, as an outdated map can result in broken scene references in runtime. You can enable it in {SettingsManager.SettingsMenuPathForDisplay}.");
 
                 return;
             }
 
             try
             {
-                SceneGuidToPathMapGenerator.Run();
+                SceneDataMapsGenerator.Run();
             }
             catch (Exception ex)
             {
-                if (SettingsManager.SceneGuidToPathMap.FailBuildIfGenerationFails.value)
+                if (SettingsManager.SceneDataMaps.FailBuildIfGenerationFails.value)
                 {
-                    Logger.Error($"Failing the build due to failure during scene GUID to path map generation. It is recommended to keep this behaviour enabled, as a failed map generation can result in broken scene references in runtime. However, if you know what you are doing, you can disable it in {SettingsManager.SettingsMenuPathForDisplay}.");
+                    Logger.Error($"Failing the build due to failure during scene data maps generation. It is recommended to keep this behaviour enabled, as a failed map generation can result in broken scene references in runtime. However, if you know what you are doing, you can disable it in {SettingsManager.SettingsMenuPathForDisplay}.");
 
                     // Only a BuildFailedException fails the build, so wrapping the original exception.
                     throw new BuildFailedException(ex);
                 }
 
-                Logger.Error($"Scene GUID to path map generation failed, but not failing the build. It is recommended to enable failing the build if the map generation fails, as a failed map generation can result in broken scene references in runtime. You can enable it in {SettingsManager.SettingsMenuPathForDisplay}.");
+                Logger.Error($"Scene data maps generation failed, but not failing the build. It is recommended to enable failing the build if the map generation fails, as a failed map generation can result in broken scene references in runtime. You can enable it in {SettingsManager.SettingsMenuPathForDisplay}.");
 
                 // Only a BuildFailedException fails the build, therefore rethrowing does not.
                 throw;

Editor/MapGeneratorTriggers/PackagesChangeListener.cs

@@ -0,0 +1,28 @@
+using UnityEditor;
+using UnityEditor.PackageManager;
+
+// TODO: run the generator only if there is a change in the packages we are interested in.
+
+namespace Eflatun.SceneReference.Editor.MapGeneratorTriggers
+{
+    [InitializeOnLoad]
+    internal static class PackagesChangeListener
+    {
+        static PackagesChangeListener()
+        {
+            UnityEditor.PackageManager.Events.registeredPackages += OnRegisteredPackages;
+        }
+
+        private static void OnRegisteredPackages(PackageRegistrationEventArgs obj)
+        {
+            if (SettingsManager.SceneDataMaps.IsGenerationTriggerEnabled(SceneDataMapsGeneratorTriggers.AfterPackagesResolve))
+            {
+                SceneDataMapsGenerator.Run();
+            }
+            else
+            {
+                Logger.Warn($"Skipping scene data maps generation after packages resolve. It is recommended to enable map generation after packages resolve, as an outdated map can result in broken scene references in runtime. You can enable it in {SettingsManager.SettingsMenuPathForDisplay}.");
+            }
+        }
+    }
+}

Editor/MapGeneratorTriggers/PlayModeListener.cs

@@ -14,16 +14,16 @@ private static void EditorApplication_OnPlayModeStateChanged(PlayModeStateChange
         {
             if (state == PlayModeStateChange.ExitingEditMode)
             {
-                if (SettingsManager.SceneGuidToPathMap.IsGenerationTriggerEnabled(SceneGuidToPathMapGenerationTriggers.BeforeEnterPlayMode))
+                if (SettingsManager.SceneDataMaps.IsGenerationTriggerEnabled(SceneDataMapsGeneratorTriggers.BeforeEnterPlayMode))
                 {
-                    SceneGuidToPathMapGenerator.Run();
+                    SceneDataMapsGenerator.Run();
                 }
                 else
                 {
                     // DESIGN: If 'Clear On Play' is enabled, this will get cleared before user gets a chance to see 
                     // it. It is easy to fix: just log in EnteredPlayMode. But that is overengineering and I don't want
                     // to do it.
-                    Logger.Warn($"Skipping scene GUID to path map generation before play mode. It is recommended to enable map generation before play mode, as an outdated map can result in broken scene references in runtime. You can enable it in {SettingsManager.SettingsMenuPathForDisplay}.");
+                    Logger.Warn($"Skipping scene data maps generation before play mode. It is recommended to enable map generation before play mode, as an outdated map can result in broken scene references in runtime. You can enable it in {SettingsManager.SettingsMenuPathForDisplay}.");
                 }
             }
         }

Editor/MapGeneratorTriggers/SceneAssetPostprocessor.cs

@@ -16,13 +16,13 @@ private static void OnPostprocessAllAssets(string[] importedAssets, string[] del
 
             if (hasSceneChange)
             {
-                if (SettingsManager.SceneGuidToPathMap.IsGenerationTriggerEnabled(SceneGuidToPathMapGenerationTriggers.AfterSceneAssetChange))
+                if (SettingsManager.SceneDataMaps.IsGenerationTriggerEnabled(SceneDataMapsGeneratorTriggers.AfterSceneAssetChange))
                 {
-                    SceneGuidToPathMapGenerator.Run();
+                    SceneDataMapsGenerator.Run();
                 }
                 else
                 {
-                    Logger.Warn($"Skipping scene GUID to path map generation after scene asset changes. It is recommended to enable map generation after scene asset changes, as an outdated map can result in broken scene references in runtime. You can enable it in {SettingsManager.SettingsMenuPathForDisplay}.");
+                    Logger.Warn($"Skipping scene data maps generation after scene asset changes. It is recommended to enable map generation after scene asset changes, as an outdated map can result in broken scene references in runtime. You can enable it in {SettingsManager.SettingsMenuPathForDisplay}.");
                 }
             }
         }

Editor/SceneDataMapsGenerator.cs

@@ -0,0 +1,102 @@
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using JetBrains.Annotations;
+using Newtonsoft.Json;
+using UnityEditor;
+
+#if ESR_ADDRESSABLES
+using UnityEditor.AddressableAssets;
+#endif // ESR_ADDRESSABLES
+
+namespace Eflatun.SceneReference.Editor
+{
+    /// <summary>
+    /// Generates and writes the scene data maps.
+    /// </summary>
+    [PublicAPI]
+    public static class SceneDataMapsGenerator
+    {
+        private const string DotKeepFileContent = "Add this file to version control. See for explanation: https://stackoverflow.com/a/17929518/6301627";
+
+        /// <summary>
+        /// Runs the generator.
+        /// </summary>
+        /// <remarks>
+        /// The menu item "Tools/Eflatun/Scene Reference/Generate Scene Data Maps" executes this method.
+        /// </remarks>
+        [MenuItem("Tools/" + Constants.MenuPrefixBase + "/Generate Scene Data Maps", priority = -3130)]
+        public static void Run()
+        {
+            try
+            {
+                Logger.Debug("Generating scene data maps.");
+
+                WriteScaffolding();
+
+                var allSceneGuids = AssetDatabase.FindAssets("t:Scene");
+
+                var sceneGuidToPathMap = GenerateSceneGuidToPathMap(allSceneGuids);
+                WriteSceneGuidToPathMap(sceneGuidToPathMap);
+
+                var sceneGuidToAddressMap = GenerateSceneGuidToAddressMap(allSceneGuids);
+                WriteSceneGuidToAddressMap(sceneGuidToAddressMap);
+            }
+            finally
+            {
+                AssetDatabase.Refresh();
+            }
+        }
+
+        private static void WriteScaffolding()
+        {
+            Directory.CreateDirectory(Paths.Absolute.SceneDataMapsFolder.PlatformPath);
+            File.WriteAllText(Paths.Absolute.SceneDataMapsDotKeepFile.PlatformPath, DotKeepFileContent);
+        }
+
+        private static Dictionary<string, string> GenerateSceneGuidToPathMap(string[] allSceneGuids)
+        {
+            var sceneGuidToPathMap = allSceneGuids.ToDictionary(
+                x => x, // key generator: take guids
+                AssetDatabase.GUIDToAssetPath // value generator: take paths
+            );
+            return sceneGuidToPathMap;
+        }
+
+        private static void WriteSceneGuidToPathMap(Dictionary<string, string> sceneGuidToPathMap)
+        {
+            var jsonRaw = JsonConvert.SerializeObject(sceneGuidToPathMap, SettingsManager.SceneDataMaps.JsonFormatting.value);
+            File.WriteAllText(Paths.Absolute.SceneGuidToPathMapFile.PlatformPath, jsonRaw);
+
+            SceneGuidToPathMapProvider.DirectAssign(sceneGuidToPathMap);
+        }
+
+        private static Dictionary<string, string> GenerateSceneGuidToAddressMap(string[] allSceneGuids)
+        {
+#if ESR_ADDRESSABLES
+            var addressableSettings = AddressableAssetSettingsDefaultObject.Settings;
+
+            var addressableSceneAssetEntries = allSceneGuids
+                .Select(addressableSettings.FindAssetEntry)
+                .Where(x => x != null);
+
+            var sceneGuidToAddressMap = addressableSceneAssetEntries.ToDictionary(
+                x => x.guid, // key generator: take guids
+                x => x.address // value generator: take addresses
+            );
+
+            return sceneGuidToAddressMap;
+#else // ESR_ADDRESSABLES
+            return new Dictionary<string, string>();
+#endif // ESR_ADDRESSABLES
+        }
+
+        private static void WriteSceneGuidToAddressMap(Dictionary<string, string> sceneGuidToAddressMap)
+        {
+            var jsonRaw = JsonConvert.SerializeObject(sceneGuidToAddressMap, SettingsManager.SceneDataMaps.JsonFormatting.value);
+            File.WriteAllText(Paths.Absolute.SceneGuidToAddressMapFile.PlatformPath, jsonRaw);
+
+            SceneGuidToAddressMapProvider.DirectAssign(sceneGuidToAddressMap);
+        }
+    }
+}

Editor/SceneGuidToPathMapGenerationTriggers.cs → Editor/SceneDataMapsGeneratorTriggers.cs

@@ -4,17 +4,19 @@
 namespace Eflatun.SceneReference.Editor
 {
     /// <summary>
-    /// Identifiers for places that perform scene GUID to path map generation generation.
+    /// Identifiers for places that trigger <see cref="SceneDataMapsGenerator"/>.
     /// </summary>
     [PublicAPI]
     [Flags]
-    public enum SceneGuidToPathMapGenerationTriggers
+    public enum SceneDataMapsGeneratorTriggers
     {
         None = 0,
         All = ~0,
-        
+
         AfterSceneAssetChange = 1 << 0,
         BeforeEnterPlayMode = 1 << 1,
         BeforeBuild = 1 << 2,
+        AfterPackagesResolve = 1 << 3,
+        AfterAddressablesChange = 1 << 4,
     }
 }