starikcetin/Eflatun.SceneReference

📦 [5.0.0] - 2026-04-12

• Compare: https://github.com/starikcetin/Eflatun.SceneReference/compare/4.1.1...5.0.0
• Thanks to @Bfihl for their contribution (#118).

💥 Breaking Changes

• `SceneReference` now implements GUID-based value equality. Two `SceneReference`s are now ruled equal if and only if they reference the same GUID.

✨ Added

• `Usage in Editor Code` README section.
• `TryGet` methods for `SceneReference` properties that can throw exceptions:
• `TryGetPath` for `Path`.
• `TryGetBuildIndex` for `BuildIndex`.
• `TryGetName` for `Name`.
• `TryGetLoadedScene` for `LoadedScene`.
• `TryGetAddress` for `Address`.

🐛 Fixed

• All GUIDs are now compared case-insensitively:
• Provider dictionaries are constructed with `StringComparer.OrdinalIgnoreCase`.
• Property drawer finds the current scene-in-build entry with `StringComparer.OrdinalIgnoreCase`.
• `Enable in Build` tool finds the scene-in-build entry with `StringComparer.OrdinalIgnoreCase`.
• Utility ignores in list mode now compare scene GUIDs with `StringComparer.OrdinalIgnoreCase`.

📦 Optimised

• Eliminated GC allocations in `IsValidGuid`.

📦 [4.1.1] - 2024-06-17

• Compare: https://github.com/starikcetin/Eflatun.SceneReference/compare/4.1.0...4.1.1

🐛 Fixed

• Fixed mistakes in README.

📦 [4.1.0] - 2024-06-16

• Compare: https://github.com/starikcetin/Eflatun.SceneReference/compare/4.0.0...4.1.0

✨ Added

• `SceneReferenceUnityEventAdapter` class: A utility `MonoBehaviour` that allows using statically provided `SceneReference`s as parameters to a `UnityEvent`.
• Utility Ignores: A set of settings that allow ignoring certain scenes from having the inline utilities.

📦 [4.0.0] - 2024-01-23

• There are fundamental changes to the editor-time behaviour in this release. Please examine carefully before upgrading.

💥 Breaking Changes

• From now on, map files are only generated during a build, and removed right after. In editor-time, maps are instead stored in and fetched from User Settings. You can remove the generated files and folders from your project, and remove the corresponding lines from your source control's ignore settings.
• `SceneDataMapsGenerator.Run` now takes a booelan argument that controls whether to ouput files or not.
• Minimum compatible Unity version is set to `2020.3.48f1`.

📋 Changed

• Default value of `EditorLogLevel` setting is now `Warning`, it was previously `Debug`.
• Default value of `JsonFormatting` setting is now `None`, it was previously `Indented`.

🐛 Fixed

• Prevent null ref exceptions during runtime caused by uninitialized map providers when the maps are missing.

🐛 Fixed

• Prevent `Scene GUID to path map file not found!` errors and null reference exceptions in `SceneAssetPostprocessor` if the scene GUID to path map file is missing.
• Prevent null reference exceptions at project launch due to addressables settings not being loaded yet.
• Ensure map files are always generated at editor startup, even if they are empty.

✨ Added

• `SceneReference.UnsafeReason` property: Provides the reasoning behind why a `SceneReference` was deemed unsafe.
• `SceneReferenceUnsafeReason` enum: Possible reasons for a `SceneReference` to be deemed unsafe.

🐛 Fixed

• `SceneDataMapsGenerator` no longer runs on scene saves.

🐛 Fixed

• Prevent null reference errors when addressables package is installed, but addressables settings are not initialized.

🐛 Fixed

• Backwards compatibility: Use `EditorStyles.miniButton` instead of non-existent `EditorStyles.iconButton` for Unity versions earlier than 2022.1.

🐛 Fixed

• Implemented workaround for a Unity bug that caused our settings page to throw exceptions and not display in Unity `2022.3.4f1`.

✨ Added

• Log level of the editor logger can now be controlled with the new setting `Logging/Editor Log Level`.

🗑️ Removed

• Removed the suggestion to output generated files as indented for source control reasons. This is because we are suggesting to ignore the generated files.

📦 [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`.
• + 11 more

✨ 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:
• + 20 more

📋 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.

✨ Added

• `Open Build Settings` button to the scene-in-build utility popups. This button will ping the scene in the project view and open build settings, allowing you to fix your build settings manually.

📋 Changed

• `Add to Build as Enabled` button is renamed to `Add to Build` in scene-in-build utility popups of scenes that are not in build.

🗑️ Removed

• `Add to Build as Disabled` button in the scene-in-build utility popups of scenes that are not in build. This button was not making much sense because adding to build as disabled doesn't actually fix the situation, since the scene will still be disabled afterwards.

💥 Breaking Changes

• Constructors and factory methods of `SceneReference` now validate their arguments and throw exceptions of type `SceneReferenceCreationException` if they are invalid. Note that the default constructor always creates an empty instance, but it never throws.
• Changed the argument name of the constructor `SceneReference(string sceneAssetGuidHex)` to `SceneReference(string guid)`.
• Changed the name of the property `SceneReference.AssetGuidHex` to `SceneReference.Guid`.
• Changed the argument name of the factory method `SceneReference.FromScenePath(string scenePath)` to `SceneReference.FromScenePath(string path)`.

✨ Added

• `SceneReference` now supports custom XML serialization via `System.Xml`.
• `SceneGuidToPathMapProvider` now also provides a path to GUID map, which is inversely equivalent to the already existing GUID to path map.
• `SceneReferenceCreationException`: Thrown when something goes wrong during the creation of a `SceneReference`.

📋 Changed

• `SceneReference` now implements serialization interfaces explicitly. This means serialization implementations are no longer exposed as `public`.
• `SceneReference` serialization implementations are now `virtual`. This means child classes can override custom serialization behaviours.
• Internal serialized field name changes:
• `SceneReference.sceneAsset` to `SceneReference.asset`
• `SceneReference.sceneAssetGuidHex` to `SceneReference.guid`

🐛 Fixed

• Prevent empty scene GUID hex in Unity serialized `SceneReference` instances.
• `SceneReference` default constructor now initailizes with an all-zero GUID as intended.
• `SceneReference` custom serialization implementations now guard against null or whitespace GUIDs.
• Prevent Unity from throwing `InvalidOperationException: Stack empty.` after inline scene-in-build utility pop-up.
• Internal bug fixes.

✨ Added

• `SceneReference` now exposes public constructors and a factory method for allowing instance creation in code:
• Empty: `new SceneReference()` constructor
• From GUID: `new SceneReference(string sceneAssetGuidHex)` constructor
• (Editor-only) From asset: `new SceneReference(UnityEngine.Object sceneAsset)` constructor
• From path: `SceneReference.FromScenePath(string scenePath)` factory method

🐛 Fixed

• Add `UNITY_EDITOR` condition to `UnityEditor` namespace import in `SceneReference`.

🐛 Fixed

• Added safeguard against situations where the scene GUID hex might be uninitialized.

✨ Added

• Support for custom serialization: `SceneReference` now implements the `ISerializable` interface and the corresponding deserialization constructor.

📦 [1.3.0] - 2022-09-05

• Compare: https://github.com/starikcetin/Eflatun.SceneReference/compare/1.2.2...1.3.0
• Thanks to @Ale1 (#23) for their contribution.

✨ Added

• Descriptive custom exceptions:
• `SceneReferenceException`: The root class of all custom exceptions of this package.
• `EmptySceneReferenceException`
• `InvalidSceneReferenceException`
• Validation properties in `SceneReference`:
• `IsSafeToUse`: Checks everything. Recommended for most use cases.
• `HasValue`
• `IsInSceneGuidToPathMap`
• + 1 more

📋 Changed

• Now throwing more descriptive custom exceptions (`EmptySceneReferenceException` and `InvalidSceneReferenceException`) for edge cases.

🐛 Fixed

• Use plaintext log prefixes (without styling) if outside Unity Editor.

📦 [1.2.2] - 2022-08-16

• Compare: https://github.com/starikcetin/Eflatun.SceneReference/compare/1.2.1...1.2.2

📋 Changed

• Improve performance of `[SceneReferenceOptions]` attribute lookup in the property drawer.

🐛 Fixed

• `[SceneReferenceOptions]` attribute not being recognized when the field is nested in other serializables.

📦 [1.2.1] - 2022-08-15

• Compare: https://github.com/starikcetin/Eflatun.SceneReference/compare/1.2.0...1.2.1

🐛 Fixed

• Generator also generates a `.keep` file in the the auto-generated map folder to make sure the folder is always tracked in version control.

📦 [1.2.0] - 2022-08-13

• Compare: https://github.com/starikcetin/Eflatun.SceneReference/compare/1.1.0...1.2.0

✨ Added

• `[SceneReferenceOptions]` attribute: Provides the ability to override scene-in-build validation settings on a per-field basis.

📋 Changed

• Moved the whole `Eflatun/Scene Reference` menu to under `Tools`. The new resulting menu path is `Tools/Eflatun/Scene Reference`.

📦 [1.1.0] - 2022-08-07

• Compare: https://github.com/starikcetin/Eflatun.SceneReference/compare/1.0.0...1.1.0

✨ Added

• Validation & inline fix utility for scenes that are either not in build or disabled in build.
• New settings entries for scene in build validation & inline fix utilities.

📦 [1.0.0] - 2022-08-03

• Initial release.