<h1 align="center">Eflatun.SceneReference</h1> <br> <p align="center"> <img src=".assets/logo.png" width="250" height="250" alt="logo" /> </p> <br> <p align="center"> Scene References for Runtime and Editor. </p> <p align="center"> Strongly typed, robust, and reliable. </p> <p align="center"> Provides GUID, Path, Build Index, Name, and Address. </p> <br> <p align="center"> <a href="https://github.com/starikcetin/Eflatun.SceneReference/"><img src="https://img.shields.io/static/v1?color=6243c4&label=GitHub&message=Eflatun.SceneReference" alt="GitHub badge"/></a> &nbsp; <a href="https://openupm.com/packages/com.eflatun.scenereference/"><img src="https://img.shields.io/npm/v/com.eflatun.scenereference?color=6243c4&label=OpenUPM&registry_uri=https://package.openupm.com" alt="OpenUPM badge"/></a> &nbsp; <a href="https://openupm.com/packages/com.eflatun.scenereference/"><img src="https://img.shields.io/badge/dynamic/json?color=6243c4&label=Downloads&suffix=/month&query=$.downloads&url=https://package.openupm.com/Downloads/point/last-month/com.eflatun.scenereference" alt="Monthly downloads badge"/></a> </p> <br>

Installation

[!IMPORTANT]<br/> Minimum compatible Unity version is 2020.3.48f1.

Get Eflatun.SceneReference

With OpenUPM (recommended)

1. Install openupm-cli via npm. You can skip this step if already have openupm-cli installed.

npm install -g openupm-cli

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

openupm add com.eflatun.scenereference

With Git URL

Add the following line to the dependencies section of your project's manifest.json file. Replace 4.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 replace 4.1.1 with upm to get the latest version instead of a specific one.

Optional Dependencies

Addressables Support

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]<br/> 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.

Usage

1. Define your SceneReference serialized 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;

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

3. 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;

Validation

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]<br/>

• Empty has priority over all other reasons.
• NotInMaps has priority over NotInBuild.

Inline Inspector Utilities

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 the Scene Reference List property.

[!NOTE]<br/> 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]<br/> 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.

Settings

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.

Addressables Support

Settings regarding addressables support.

[!NOTE]<br/> Settings under this category are only relevant if addressables support is enabled.

Color Addressable Scenes

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]<br/> 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.

Logging

Settings regarding logging.

[!NOTE]<br/> Exceptions will always be logged.

Editor Log Level

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

Property Drawer

Settings regarding the property drawer.

Show Inline Toolbox

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.

Color Based On Scene-In-Build State

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.