Repository files navigation

Scene References for Runtime and Editor.

Strongly typed, robust, and reliable.

Provides GUID, Path, Build Index, Name, and Address.

1. Installopenupm-cli vianpm. You can skip this step if already haveopenupm-cli installed.

npm install -g openupm-cli

2. Installcom.eflatun.scenereference in your project. Make sure to run this command at the root of your Unity project.

openupm add com.eflatun.scenereference

Add the following line to thedependencies section of your project'smanifest.json file. Replace4.1.1 with the version you want to install.

"com.eflatun.scenereference":"git+https://github.com/starikcetin/Eflatun.SceneReference.git#4.1.1"

Although it is highly discouraged, you can replace4.1.1 withupm 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 theAddressables Package Documentation for information on how to install addressables package in your project.

1. Define yourSceneReference serialized field:

// Import Runtime namespaceusingEflatun.SceneReference;// You can define it by itself[SerializeField]privateSceneReferencemySceneReference;// Or in a collection[SerializeField]privateList<SceneReference>mySceneReferences;

2. Assign your scene to yourSceneReference field in the inspector:

3. Use it!

// Import Runtime namespaceusingEflatun.SceneReference;// You can access these anytime, anywherevarsceneGuid=mySceneReference.Guid;varscenePath=mySceneReference.Path;varsceneBuildIndex=mySceneReference.BuildIndex;varsceneName=mySceneReference.Name;// You can only access these when the scene is currently loadedvarloadedScene=mySceneReference.LoadedScene// You can only access these if you have addressables support enabledvar sceneAddress=mySceneReference.Address;

You can checkState property to make sure aSceneReference is completely valid before using it. It will also give you information regarding the type of the scene it references.

// Import Runtime namespaceusingEflatun.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 aSceneReference is deemed unsafe, you can check theUnsafeReason property.

// Import Runtime namespaceusingEflatun.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.}

A scene will be accessible in runtime only if one of the following is true:

1. The scene is added and enabled in build settings.
2. 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 A field is assigned a scene that is added and enabled in build settings. All good here.
• Scene B field is assigned a scene that is disabled in build settings.
• Scene C field is assigned a scene that is neither in build settings nor addressable.
• Scene D filds is assigned an addressable scene. Again, all good here.
• Scene E field is not assigned anything. It is empty.
• Similarly for theScene Reference List property.

If we click on the little gear (⚙️) icon to the right of the field, a toolbox popup will open that contains the fix utilities. ForScene B field, we get the following tools:

And forScene C field, we get the following tools:

Clicking on theEnable in build... button gives us this prompt:

Add to build... button gives the following prompt:

AndMake 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 theProject Settings.

Open the project settings viaEdit/Project Settings... menu item.

Look for theEflatun category in the left panel. Select theScene Reference item.

Settings regarding addressables support.

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

Settings regarding logging.

Log level for the editor logger. It is recommended to leave this atWarning.

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.

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 atAll unless you are debugging something. Failure to generate the maps when needed can result in broken scene references in runtime.

Controls the Scene Data Maps Generator's JSON formatting.

It is recommended to leave this option atNone as it will make the generated files smaller in size.

Should we fail a build if scene data maps generation fails?

Only relevant ifBefore Build generation trigger is enabled.

It is recommended to leave this option attrue, as a failed map generation can result in broken scene references in runtime.

Settings for preventing certain scenes from having inline utilities.

The mode of operation for preventing certain scenes from having the inline coloring/toolbox utility.

• Disabled: Nothing will be ignored.

• List: The scenes in theColoring Ignores List /Toolbox Ignores List will not be colored / will not have toolboxes.

• Patterns: The scenes with paths matching the patterns in theColoring Ignore Patterns /Toolbox Ignore Patterns text box will not be colored / will not have toolboxes.

The scenes in this list will not be colored / will not have toolboxes. This setting is visible only whenColoring Ignore Mode /Toolbox Ignore Mode is set toList.

The scenes with paths matching the patterns in this setting will not be colored / will not have toolboxes. This setting is visible only whenColoring Ignore Mode /Toolbox Ignore Mode is set toPatterns.

Eflatun.SceneReference outputs generated maps to three locations:

1. JSON files underAssets/Resources. They all start withEflatun_SceneReference_ and end with.generated.json.
2. UserSettings.
3. 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:

1. Manaully running the generator via the relevant menu item.
2. During a build if theBefore Build generation trigger is enabled.

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 underTools/Eflatun/Scene Reference/Generate Scene Data Maps:

You can trigger the generator from your editor code:

// Import Editor namespaceusingEflatun.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 manipulateEflatun.SceneReference settings from your editor code.

// Import the Editor namespaceusingEflatun.SceneReference.Editor;// Access a setting. Only do this in Editor code!vargenerationTriggers=SettingsManager.SceneDataMaps.GenerationTriggers;// Change a setting. Only do this in Editor code!SettingsManager.SceneDataMaps.GenerationTriggers=GenerationTriggers.All;

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 duringRuntimeInitializeLoadType.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 Unityreloading 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:

1. Generator runs and directly assigns the map to the providers.
2. Something happens which triggers Unity toreload the domain.
3. You access the map from a provider.
4. Provider checks to see if it still has the map values, and realizes they are lost.
5. Provider parses the map file/store.

TheSceneGuidToPathMapProvider 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 namespaceusingEflatun.SceneReference;// Get the scene path from a scene GUID. You can do this both in runtime and in editor.varscenePath=SceneGuidToPathMapProvider.SceneGuidToPathMap[sceneGuid];// Get the scene GUID from a scene path. You can do this both in runtime and in editor.varsceneGuid=SceneGuidToPathMapProvider.ScenePathToGuidMap[scenePath];

TheSceneGuidToAddressMapProvider static class is responsible for providing the scene GUID to scene address mapping to the rest of the code. UnlikeSceneGuidToPathMapProvider, 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 calledGetGuidFromAddress andTryGetGuidFromAddress that serve the same purpose.

Getting the GUID from address can fail in following cases:

1. No scene with the given address found in the map (AddressNotFoundException).
2. Multiple scenes found with the given address in the map (AddressNotUniqueException).
3. Addressables support is disabled (AddressablesSupportDisabledException).

// Import the Runtime namespaceusingEflatun.SceneReference;// Get the scene address from a scene GUID. You can do this both in runtime and in editor.varsceneAddress=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.varsceneGuid=SceneGuidToAddressMapProvider.GetGuidFromAddress(sceneAddress);// Second way. Returns a bool that represents success or failure.if(SceneGuidToAddressMapProvider.TryGetGuidFromAddress(sceneAddress,outvarsceneGuid)){// 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]privateSceneReferencescene;

For all arguments, passingEnabled orDisabled 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 isDoNotOverride. For example, the following code disables the toolbox, but makes coloring respect project settings:

[SceneReferenceOptions(Toolbox=ToolboxBehaviour.Disabled)][SerializeField]privateSceneReferencescene;

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, pleaseopen an issue.

ExampleSceneReference serialization to Json and back viaNewtonsoft.Json:

usingEflatun.SceneReference;usingNewtonsoft.Json;// SerializeSceneReferencesceneRef=/* ... */;varserialized=JsonConvert.SerializeObject(sceneRef);// Deserializestringjson=/* ... */;SceneReferencedeserialized=JsonConvert.DeserializeObject<SceneReference>(json);

ExampleSceneReference serialization to binary and back viaSystem.Runtime.Serialization.Formatters.Binary:

usingEflatun.SceneReference;usingSystem;usingSystem.IO;usingSystem.Runtime.Serialization.Formatters.Binary;// SerializeSceneReferencesceneRef=/* ... */;varbf=newBinaryFormatter();usingvarms=newMemoryStream();bf.Serialize(ms,sceneRef);varserializedBytes=ms.ToArray();varserializedBase64=Convert.ToBase64String(serializedBytes);// Deserializebyte[]bytes=/* ... */;varbf=newBinaryFormatter();usingvarms=newMemoryStream(bytes);SceneReferencedeserialized=bf.Deserialize(ms)asSceneReference;

ExampleSceneReference serialization to XML and back viaSystem.Xml:

usingEflatun.SceneReference;usingSystem.IO;usingSystem.Text;usingSystem.Xml;usingSystem.Xml.Serialization;// SerializeSceneReferencesceneRef=/* ... */;varxmlSerializer=newXmlSerializer(typeof(SceneReference));varsb=newStringBuilder();usingvarxmlWriter=XmlWriter.Create(sb);xmlSerializer.Serialize(xmlWriter,sceneRef);varserialized=sb.ToString();// Deserializestringxml=/* ... */;varxmlSerializer=newXmlSerializer(typeof(SceneReference));usingvarstringReader=newStringReader(xml);usingvarxmlReader=XmlReader.Create(stringReader);SceneReferencedeserialized=xmlSerializer.Deserialize(xmlReader)asSceneReference;

You can create instances ofSceneReference in code. To facilitate this, it exposes constructors and factory methods.

// Empty (and subsequently invalid)varempty=newSceneReference();// From Scene GUIDstringsceneGuid=/* ... */;varfromSceneGuid=newSceneReference(sceneGuid);// From Scene PathstringscenePath=/* ... */;varfromScenePath=SceneReference.FromScenePath(scenePath);// Fom Scene Address// Will throw AddressablesSupportDisabledException if addressables support is disabled.stringsceneAddress=/* ... */;varfromSceneAddress=SceneReference.FromAddress(sceneAddress);// From Scene Asset// You can only do this in Editor code.UnityEngine.ObjectsceneAsset=/* ... */;varfromSceneAsset=newSceneReference(sceneAsset);

There are two ways you can fill-in parameters of a listener when you are invoking them via aUnityEvent:

Dynamically provided parameters are filled in by the code that invokes the event. You do not assign them in the inspector. In this case, you do not need to do anything special. Simply connect aUnityEvent<SceneReference> to a method that accepts aSceneReference as a parameter and it will work.

Example of aUnityEvent emitter and a listener that can use a dynamically providedSceneReference parameter:

publicclassEmitter:MonoBehaviour{publicSceneReferencescene;publicUnityEvent<SceneReference>raised;voidRaise(){raised.Invoke(scene);}}publicclassListener:MonoBehaviour{publicvoidListen(SceneReferencescene){// ...}}

Statically assigned parameters are those that the listener takes in, but the emitter doesn't provide. Therefore Unity asks you to fill them in yourself during the wiring of the event. If you are doing this in the inspector, then you won't be able to fill a missingSceneReference in there. In fact, Unity won't even allow you to select a method as a listener that requires aSceneReference to be assigned statically.

Example of aUnityEvent emitter and a listener that requires aSceneReference parameter to be filled in statically:

publicclassEmitter:MonoBehaviour{publicUnityEventraised;voidRaise(){raised.Invoke();}}publicclassListener:MonoBehaviour{publicvoidListen(SceneReferencescene){// ...}}

As a workaround, we provide you with aSceneReferenceUnityEventAdapter class that allows you to indirectly use a statically assignedSceneReference parameter to aUnityEvent listener by acting as an adapter between the emitters and listeners. Please investigate the screenshot below to see how the emitter-side is set up, and the code block below that to see how the listener-side looks.

publicclassSceneLoader:MonoBehaviour{publicvoidLoadScene(SceneReferencescene){// ...}}

In the screenshot, theOnClick event of the button is being listened by theRaise method of the adapter. TheRaised event of the adapter is being listened by theLoadScene method of the scene loader class. Notice theScene serialized field on the adapter. Thescene parameter ofLoadScene method of the scene loader class is filled with theScene serialized field of the adapter. This way, while we are unable to wireLoadScene andOnClick directly together, we can wire them through theSceneReferenceUnityEventAdapter class acting as a middleman.

Depending on the visibility of your field, you have different options on how to display, get, and set a field of typeEflatun.SceneReference in your editor code.

Let's assume we have the followingMonoBehaviour that we are writing a custom editor for:

publicclassCustomEditorUsageDemo:MonoBehaviour{publicSceneReferencePublicScene;[SerializeField]privateSceneReferenceprivateScene;}

Use this option if you do not care about the underlying data, and want to letSceneReference field do its thing.

varserializedProp=serializedObject.FindProperty("privateScene");EditorGUILayout.PropertyField(serializedProp);

Use this option if:

1. You need to get or set the underlyingSceneReference instance of the field yourself.
2. The field is visible to your editor code.

vartargetCasted=(CustomEditorUsageDemo)target;// readvarvalue=targetCasted.PublicScene;// writetargetCasted.PublicScene=SceneReference.FromScenePath(_newPathPublicSceneDirect);

Use this option if:

1. You need to get or set the underlyingSceneReference instance of the field yourself.
2. The field is not visible to your editor code.
3. Your Unity version is Unity 2022.1 or newer.

varserializedProp=serializedObject.FindProperty("privateScene");// readvarvalue=serializedProp.boxedValueasSceneReference;// writeserializedProp.boxedValue=SceneReference.FromScenePath(/* ... */);

Use this option if:

1. You need to get or set the underlyingSceneReference instance of the field yourself.
2. The field is not visible to your editor code.
3. Your Unity version is older than 2022.1.

varfieldInfo=target.GetType().GetField("privateScene",BindingFlags.NonPublic|BindingFlags.Instance);// getvarvalue=fieldInfo.GetValue(target)asSceneReference;// setfieldInfo.SetValue(target,SceneReference.FromScenePath(/* ... */));

Thrown if aSceneReference is empty (not assigned anything).

To fix it, make sure theSceneReference is assigned a valid scene asset.

You can avoid it by making sure theState property is notUnsafe.

Thrown if aSceneReference is invalid. This can happen for these reasons:

1. TheSceneReference is assigned an invalid scene, or the assigned asset is not a scene. To fix this, make sure theSceneReference is assigned a valid scene asset.

2. 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 theState property is notUnsafe.

Thrown when something goes wrong during the creation of aSceneReference.

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:

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

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

Thrown if a given address matches multiple entries in the Scene GUID to Address Map. This can happen for these reasons:

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

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

Thrown if addressables-specific operations are attempted on aSceneReference that is assigned a non-addressable scene.

You can avoid this exception by making sure theState property isAddressable.

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 byopening an issue and including the relevant information in the exception message.

• This project is inspired byJohannesMP'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 byAngular's README.

• This project usesgoelhardik's ignore for matching glob patterns.

If this project doesn't suit your needs, you can always let me know byopening an issue orcreating 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 theLICENSE.md file.

Copyright (c) 2022S. Tarık Çetin