Scene References for Runtime and Editor.
Strongly typed, robust, and reliable.
Provides GUID, Path, Build Index, Name, and Address.
Important
Minimum compatible Unity version is 2020.3.48f1.
- Install
openupm-clivianpm. You can skip this step if already haveopenupm-cliinstalled.
npm install -g openupm-cli- Install
com.eflatun.scenereferencein your project. Make sure to run this command at the root of your Unity project.
openupm add com.eflatun.scenereferenceAdd the following line to the dependencies section of your project's manifest.json file. Replace 4.0.0 with the version you want to install.
"com.eflatun.scenereference": "git+https://github.com/starikcetin/Eflatun.SceneReference.git#4.0.0"Although it is highly discouraged, you can replace 4.0.0 with upm to get the latest version instead of a specific one.
Eflatun.SceneReference has support for addressables. It will be enabled or disabled automatically depending on whether you have the addressables package installed in your project. Please refer to the Addressables Package Documentation for information on how to install addressables package in your project.
Note
As a deliberate design decision in accordance with the Principle of least astonishment, the public API and settings that concern addressables will still be visible even if addressables support is disabled. This way, if you later decide to uninstall addressables from your project, you will not face an overwhelming amount of compiler errors. This enables you to transition between using and not using addressables with only a minimal amount of refactors.
- Define your
SceneReferenceserialized field:
// Import Runtime namespace
using Eflatun.SceneReference;
// You can define it by itself
[SerializeField] private SceneReference mySceneReference;
// Or in a collection
[SerializeField] private List<SceneReference> mySceneReferences;- Assign your scene to your
SceneReferencefield in the inspector:
- Use it!
// Import Runtime namespace
using Eflatun.SceneReference;
// You can access these anytime, anywhere
var sceneGuid = mySceneReference.Guid;
var scenePath = mySceneReference.Path;
var sceneBuildIndex = mySceneReference.BuildIndex;
var sceneName = mySceneReference.Name;
// You can only access these when the scene is currently loaded
var loadedScene = mySceneReference.LoadedScene
// You can only access these if you have addressables support enabled
var sceneAddress = mySceneReference.Address;You can check State property to make sure a SceneReference is completely valid before using it. It will also give you information regarding the type of the scene it references.
// Import Runtime namespace
using Eflatun.SceneReference;
if (mySceneReference.State == SceneReferenceState.Unsafe)
{
// The scene is not safe to use. Something is wrong.
}
if (mySceneReference.State == SceneReferenceState.Regular)
{
// The scene is safe to use. It references a regular scene.
}
// If you have addressables support enabled, you can also get this state:
if (mySceneReference.State == SceneReferenceState.Addressable)
{
// The scene is safe to use. It references an addressable scene.
}If you need to know why a SceneReference is deemed unsafe, you can check the UnsafeReason property.
// Import Runtime namespace
using Eflatun.SceneReference;
if (mySceneReference.UnsafeReason == SceneReferenceUnsafeReason.None)
{
// All good. Safe to use.
}
if (mySceneReference.UnsafeReason == SceneReferenceUnsafeReason.Empty)
{
// mySceneReference is empty. It is not referencing anything.
}
if (mySceneReference.UnsafeReason == SceneReferenceUnsafeReason.NotInMaps)
{
// The scene referenced by mySceneReference is not found in any of the maps.
}
if (mySceneReference.UnsafeReason == SceneReferenceUnsafeReason.NotInBuild)
{
// The scene referenced by mySceneReference is not added and enabled in build.
}Important
Emptyhas priority over all other reasons.NotInMapshas priority overNotInBuild.
A scene will be accessible in runtime only if one of the following is true:
- The scene is added and enabled in build settings.
- The scene is in an addressables group.
Eflatun.SceneReference on the other hand, allows you to assign onto it any scene you wish. This behaviour may cause runtime bugs when loading scenes. To prevent these potential bugs, Eflatun.SceneReference provides inline inspector utilities.
In this example:
Scene Afield is assigned a scene that is added and enabled in build settings. All good here.Scene Bfield is assigned a scene that is disabled in build settings.Scene Cfield is assigned a scene that is neither in build settings nor addressable.Scene Dfilds is assigned an addressable scene. Again, all good here.Scene Efield is not assigned anything. It is empty.- Similarly for the
Scene Reference Listproperty.
Note
Addressable scenes are only available if addressables support is enabled.
If we click on the little gear (⚙️) icon to the right of the field, a toolbox popup will open that contains the fix utilities. For Scene B field, we get the following tools:
And for Scene C field, we get the following tools:
Note
You will only see the Make addressable... tool if addressables support is enabled.
Clicking on the Enable in build... button gives us this prompt:
Add to build... button gives the following prompt:
And Make addressable... button gives the following prompt:
Using these prompts, we can quickly alleviate the situation, and prevent potential runtime bugs when using these scenes.
Eflatun.SceneReference provides settings under the Project Settings.
Open the project settings via Edit/Project Settings... menu item.
Look for the Eflatun category in the left panel. Select the Scene Reference item.
Settings regarding addressables support.
Note
Settings under this category are only relevant if addressables support is enabled.
Should we color the property to draw attention for addressable scenes?
Addressable scenes should be handled differently than regular scenes in runtime, through the addressables API. Therefore, you would want quickly identify if an Eflatun.SceneReference references an addressable scene or not.
It is recommended to leave this option at 'true', as it will help you easily distinguish addressable scenes.
Note
This setting does not apply to regular scenes. They have their own coloring mechanism. It is controlled by the Color Based On Scene-In-Build State setting under the Property Drawer category.
Settings regarding logging.
Note
Exceptions will always be logged.
Log level for the editor logger. It is recommended to leave this at Warning.
Settings regarding the property drawer.
Should we show the inline gear (⚙️) button that opens a toolbox?
Unity only bundles scenes that are added and enabled in build settings, and addressables only pack scenes that are in an Addressable Group. Therefore, you would want to make sure the scene you assign to a SceneReference is either added and enabled in build settings, or is in an addressable group. The toolbox provides tools for you to quickly take action in these cases.
It is recommended to leave this option enabled, as the toolbox saves you a lot of time.
Should we color the property to draw attention for scenes that are either not in build or disabled in build?
Unity only bundles scenes that are added and enabled in build settings. Therefore, you would want to validate whether the scene you assign to a SceneReference is added and enabled in build settings.
It is recommended to leave this option at 'true', as it will help you identify many potential runtime errors.
Note
This setting does not apply to addressable scenes. They have their own coloring mechanism. It is controlled by the Color Addressable Scenes setting under the Addressables Support category.
Settings regarding the scene data maps and the generator.
Controls when the scene data maps get regenerated.
-
After Scene Asset Change: Regenerate the maps every time a scene asset changes (delete, create, move, rename).
-
Before Enter Play Mode: Regenerate the maps before entering play mode in the editor.
-
Before Build: Regenerate the maps before a build.
-
After Packages Resolve: Regenerate the maps after UPM packages are resolved.
-
After Addressables Change: Regenerate the maps after addressable group entries change. Only relevant if you have addressables support enabled.
It is recommended that you leave this option at All unless you are debugging something. Failure to generate the maps when needed can result in broken scene references in runtime.
Note
All and Everything are the same thing. They both represent all triggers.
Controls the Scene Data Maps Generator's JSON formatting.
It is recommended to leave this option at None as it will make the generated files smaller in size.
Should we fail a build if scene data maps generation fails?
Only relevant if Before Build generation trigger is enabled.
It is recommended to leave this option at true, as a failed map generation can result in broken scene references in runtime.
Eflatun.SceneReference outputs generated maps to three locations:
- JSON files under
Assets/Resources. They all start withEflatun_SceneReference_and end with.generated.json. UserSettings.- Internal direct assign to the providers.
The steps 2 and 3 run for all generations. The JSON files on the other hand, will only be generated in two circumstances:
- Manaully running the generator via the relevant menu item.
- During a build if the Before Build generation trigger is enabled.
Note
If the Before Build generation trigger is enabled, JSON map files will also be cleaned up after a build.
Warning
Map files are auto-generated, do not edit them. Any edits will be lost at the next generation.
The generator runs automatically according to the triggers selected in the settings. However, if for some reason you need to run the generator yourself, you can do so.
Running the generator has no side-effects (other than the JSON file output if you select the corresponding option).
You can trigger the generator via a menu item. Find it under Tools/Eflatun/Scene Reference/Generate Scene Data Maps:
Tip
Automatic generation (i.e. generation triggers) only outputs files during a build. With menu items, you decide whether to output files or not.
You can trigger the generator from your editor code:
// Import Editor namespace
using Eflatun.SceneReference.Editor;
// Run the generator and output files. Only do this in Editor code!
SceneDataMapsGenerator.Run(true);
// Run the generator and but do not output files. Only do this in Editor code!
SceneDataMapsGenerator.Run(false);You can read and manipulate Eflatun.SceneReference settings from your editor code.
// Import the Editor namespace
using Eflatun.SceneReference.Editor;
// Access a setting. Only do this in Editor code!
var generationTriggers = SettingsManager.SceneDataMaps.GenerationTriggers;
// Change a setting. Only do this in Editor code!
SettingsManager.SceneDataMaps.GenerationTriggers = GenerationTriggers.All;Warning
Changing settings from code may have unintended consequences. Make sure you know what you are doing.
You can access the maps directly from both runtime and editor code. There are no side effects of accessing the maps directly.
In runtime, there are no performance penalties. The generated file is parsed automatically either upon the first access to the maps from a provider or during RuntimeInitializeLoadType.BeforeSceneLoad, whichever comes first. It is guaranteed that the generated file is parsed only once. Each provider does this for itself, there is no coordination between them.
In editor, there are also no performance penalties except for one case. The generator assigns the map directly to the providers upon every generation. This prevents unnecessarily parsing the map file/store. However, if the providers lose the values assigned by the generator due to Unity reloading the domain, and some code tries to access the map before the generator runs again, then the providers have to parse the map file/store themselves. This is what happens in that scenario:
- Generator runs and directly assigns the map to the providers.
- Something happens which triggers Unity to reload the domain.
- You access the map from a provider.
- Provider checks to see if it still has the map values, and realizes they are lost.
- Provider parses the map file/store.
The SceneGuidToPathMapProvider static class is responsible for providing the scene GUID to scene path mapping to the rest of the code. There are two maps, one maps from GUIDs to paths, and the other one maps from paths to GUIDs. Both maps are inversely equivalent.
// Import the Runtime namespace
using Eflatun.SceneReference;
// Get the scene path from a scene GUID. You can do this both in runtime and in editor.
var scenePath = SceneGuidToPathMapProvider.SceneGuidToPathMap[sceneGuid];
// Get the scene GUID from a scene path. You can do this both in runtime and in editor.
var sceneGuid = SceneGuidToPathMapProvider.ScenePathToGuidMap[scenePath];Note
This map is only relevant if addressables support is enabled.
The SceneGuidToAddressMapProvider static class is responsible for providing the scene GUID to scene address mapping to the rest of the code. Unlike SceneGuidToPathMapProvider, this class cannot provide an inverse map, because the address of an asset is not guaranteed to be unique due to the design of addressables. Instead, it provides two methods called GetGuidFromAddress and TryGetGuidFromAddress that serve the same purpose.
Getting the GUID from address can fail in following cases:
- No scene with the given address found in the map (
AddressNotFoundException). - Multiple scenes found with the given address in the map (
AddressNotUniqueException). - Addressables support is disabled (
AddressablesSupportDisabledException).
// Import the Runtime namespace
using Eflatun.SceneReference;
// Get the scene address from a scene GUID. You can do this both in runtime and in editor.
var sceneAddress = SceneGuidToAddressMapProvider.SceneGuidToAddressMap[sceneGuid];
// Get the scene GUID from a scene address. You can do this both in runtime and in editor.
// First way. Will throw exceptions on faliure.
var sceneGuid = SceneGuidToAddressMapProvider.GetGuidFromAddress(sceneAddress);
// Second way. Returns a bool that represents success or failure.
if(SceneGuidToAddressMapProvider.TryGetGuidFromAddress(sceneAddress, out var sceneGuid))
{
// Success. sceneGuid is valid.
}
else
{
// Failure. sceneGuid is invalid.
}You can override the inline inspector utility project settings on a per-field basis using the [SceneReferenceOptions] attribute. For example, in order to disable all inline utilities, use the attribute as such:
[SceneReferenceOptions(SceneInBuildColoring = ColoringBehaviour.Disabled, Toolbox = ToolboxBehaviour.Disabled, AddressableColoring = ColoringBehaviour.Disabled)]
[SerializeField] private SceneReference scene;For all arguments, passing Enabled or Disabled will force that behaviour to be enabled or disabled respectively, disregarding the project settings. DoNotOverride makes the argument respect the project settings. DoNotOverride is the default value.
You don't have to supply both fields at once. Missing fields will have the default value, which is DoNotOverride. For example, the following code disables the toolbox, but makes coloring respect project settings:
[SceneReferenceOptions(Toolbox = ToolboxBehaviour.Disabled)]
[SerializeField] private SceneReference scene;Note
AddressableColoring argument is only relevant if addressables support is enabled.
Serializers listed under this section are tested and supported.
If you come across any problems while using these serializers, or if you want another serializer to be supported, please open an issue.
Example SceneReference serialization to Json and back via Newtonsoft.Json:
using Eflatun.SceneReference;
using Newtonsoft.Json;
// Serialize
SceneReference sceneRef = /* ... */;
var serialized = JsonConvert.SerializeObject(sceneRef);
// Deserialize
string json = /* ... */;
SceneReference deserialized = JsonConvert.DeserializeObject<SceneReference>(json);Caution
We strongly advise against using BinaryFormatter as it is inconsistent and has inherent security risks. Only use it if you absolutely have to.
Example SceneReference serialization to binary and back via System.Runtime.Serialization.Formatters.Binary:
using Eflatun.SceneReference;
using System;
using System.IO;
using System.Runtime.Serialization.Formatters.Binary;
// Serialize
SceneReference sceneRef = /* ... */;
var bf = new BinaryFormatter();
using var ms = new MemoryStream();
bf.Serialize(ms, sceneRef);
var serializedBytes = ms.ToArray();
var serializedBase64 = Convert.ToBase64String(serializedBytes);
// Deserialize
byte[] bytes = /* ... */;
var bf = new BinaryFormatter();
using var ms = new MemoryStream(bytes);
SceneReference deserialized = bf.Deserialize(ms) as SceneReference;Example SceneReference serialization to XML and back via System.Xml:
using Eflatun.SceneReference;
using System.IO;
using System.Text;
using System.Xml;
using System.Xml.Serialization;
// Serialize
SceneReference sceneRef = /* ... */;
var xmlSerializer = new XmlSerializer(typeof(SceneReference));
var sb = new StringBuilder();
using var xmlWriter = XmlWriter.Create(sb);
xmlSerializer.Serialize(xmlWriter, sceneRef);
var serialized = sb.ToString();
// Deserialize
string xml = /* ... */;
var xmlSerializer = new XmlSerializer(typeof(SceneReference));
using var stringReader = new StringReader(xml);
using var xmlReader = XmlReader.Create(stringReader);
SceneReference deserialized = xmlSerializer.Deserialize(xmlReader) as SceneReference;You can create instances of SceneReference in code. To facilitate this, it exposes constructors and factory methods.
// Empty (and subsequently invalid)
var empty = new SceneReference();
// From Scene GUID
string sceneGuid = /* ... */;
var fromSceneGuid = new SceneReference(sceneGuid);
// From Scene Path
string scenePath = /* ... */;
var fromScenePath = SceneReference.FromScenePath(scenePath);
// Fom Scene Address
// Will throw AddressablesSupportDisabledException if addressables support is disabled.
string sceneAddress = /* ... */;
var fromSceneAddress = SceneReference.FromAddress(sceneAddress);
// From Scene Asset
// You can only do this in Editor code.
UnityEngine.Object sceneAsset = /* ... */;
var fromSceneAsset = new SceneReference(sceneAsset);Important
- Constructors and factory methods validate their arguments and throw exceptions of type
SceneReferenceCreationExceptionif they are invalid. - The default constructor always creates an empty instance, but it never throws.
FromAddressfactory method throwsAddressablesSupportDisabledExceptionif addressables support is disabled.
Caution
The constructor that accepts a scene asset of type UnityEngine.Object is for Editor use only. Do NOT use it in runtime code.
Thrown if a SceneReference is empty (not assigned anything).
To fix it, make sure the SceneReference is assigned a valid scene asset.
You can avoid it by making sure the State property is not Unsafe.
Thrown if a SceneReference is invalid. This can happen for these reasons:
-
The
SceneReferenceis assigned an invalid scene, or the assigned asset is not a scene. To fix this, make sure theSceneReferenceis assigned a valid scene asset. -
The Scene GUID to Path Map is outdated. To fix this, you can either manually run the map generator, or enable all generation triggers. It is highly recommended to keep all the generation triggers enabled.
You can avoid it by making sure the State property is not Unsafe.
Thrown when something goes wrong during the creation of a SceneReference.
It can happen for many different reasons.
The exception message contains the particular reason and suggestions on how to fix it.
Thrown if a given address is not found in the Scene GUID to Address Map. This can happen for these reasons:
-
The asset with the given address either doesn't exist or is not a scene. To fix this, make sure you provide the address of a valid scene.
-
The Scene GUID to Address Map is outdated. To fix this, you can either manually run the generator, or enable generation triggers. It is highly recommended to keep all the generation triggers enabled.
Note
This exception will never be thrown if addressables support is disabled.
Thrown if a given address matches multiple entries in the Scene GUID to Address Map. This can happen for these reasons:
-
There are multiple addressable scenes with the same given address. To fix this, make sure there is only one addressable scene with the given address.
-
The Scene GUID to Address Map is outdated. To fix this, you can either manually run the generator, or enable generation triggers. It is highly recommended to keep all the generation triggers enabled.
Note
This exception will never be thrown if addressables support is disabled.
Thrown if addressables-specific operations are attempted on a SceneReference that is assigned a non-addressable scene.
You can avoid this exception by making sure the State property is Addressable.
Note
This exception will never be thrown if addressables support is disabled.
Thrown if an operation that requires addressables support is attempted while addressables support is disabled.
To fix it, make sure addressables support is enabled.
This exception is not part of the public API. It indicates that something has gone wrong internally. It is not meant to be catched, fixed, or avoided by user code.
If you come across this exception, make sure to create a bug report by opening an issue and including the relevant information in the exception message.
-
This project is inspired by JohannesMP's SceneReference. For many years I have used his original implementation of a runtime Scene Reference. Many thanks to @JohannesMP for saving me countless hours of debugging, and inspiring me to come up with a more robust way to tackle this problem that Unity refuses to solve.
-
README header inspired by Angular's README.
If this project doesn't suit your needs, you can always let me know by opening an issue or creating a discussion and I will see what we can do about it. If you think you absolutely need another approach, here are some similar projects to check out:
- https://github.com/JohannesMP/unity-scene-reference
- https://github.com/NibbleByte/UnitySceneReference
MIT License. Refer to the LICENSE.md file.
Copyright (c) 2022 S. Tarık Çetin
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent