Eflatun.SceneReference: typed scene references for Unity

The problem with a scene name in a string field

The ordinary Unity way to point a field at a scene is to store the scene name as a string and load it with SceneManager.LoadScene. The failure mode is well known: rename a scene in the project window and the string in the serialized field still holds the old name, the load call quietly does nothing or throws at runtime, and nothing in the editor flags it.

Eflatun.SceneReference replaces that string with a serialized field of type SceneReference, drawn in the inspector as a scene picker. The package description says it provides GUID, Path, Build Index, Name and Address, and that it is strongly typed, which in this context means the reference resolves at load time to actual scene metadata rather than to a name you have to look up.

The audience is any team shipping a Unity project where scenes are loaded from code, from a save system, or from a flow that depends on a specific scene existing in the build. The package is published on OpenUPM as com.eflatun.scenereference and the homepage is its OpenUPM package page.

The minimum compatible Unity version is stated in an important callout at the top of the installation section: 2020.3.48f1.

Installing through OpenUPM or a Git URL

The recommended route is OpenUPM, which means installing a small command line tool first.

npm install -g openupm-cli

That step can be skipped if openupm-cli is already present. With the tool in place, the package is added from the root of the Unity project.

openupm add com.eflatun.scenereference

The alternative is a Git URL added to the dependencies section of the project's manifest.json, with the version substituted as needed.

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

The README is explicit that replacing the version with `upm` to track the latest release is highly discouraged. For a package that other people's code depends on, pinning a version is the difference between a reproducible build and one that changes underneath you.

The repository also ships a publish.sh script and the package lives under an Eflatun.SceneReference/ directory, so the layout matches the usual Unity package convention with a manifest and package content folder.

Declaring and reading a scene reference

A reference is a serialized field, either on its own or inside a collection.

// 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;

The scene is then assigned in the inspector rather than typed as text, which is the step that removes the rename hazard.

Reading the reference exposes several members, and the README is careful about which ones are safe to touch at which moment. Guid, Path, BuildIndex and Name are available any time and anywhere. LoadedScene can only be accessed when the scene is currently loaded. Address can only be accessed if addressables support is enabled.

// 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;

That split is the design decision worth internalising. A reference to a scene that is not in the build is not a null reference, it is a reference to something that will never load, and the property access is where that mistake is caught.

State and UnsafeReason before you touch a reference

The package asks you to check the State property before using a reference, and it also reports the scene type.

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

When the state is Unsafe, the UnsafeReason property says why, with an enum per failure mode. Empty means the reference points at nothing. NotInMaps means the referenced scene is not found in any of the maps. NotInBuild means the scene is not added and enabled in the build.

The ordering rules are stated explicitly. Empty has priority over every other reason, and NotInMaps has priority over NotInBuild. So a single UnsafeReason read gives you the most fundamental problem, not an arbitrary one from a set, which makes it usable as a single branch in validation code rather than a list to check in the right order by hand.

The distinction between Regular and Addressable matters in a project that mixes both, since the two scene types have different runtime behaviour and the reference tells you which one you are holding.

TryGet methods instead of exceptions

Every property that can throw based on state has a matching TryGet method, and the README describes them as an alternative to validating first and then reading.

if (mySceneReference.TryGetPath(out var path))
{
    // `path` contains the value of `mySceneReference.Path`.
}

if (mySceneReference.TryGetBuildIndex(out var buildIndex))
{
    // `buildIndex` contains the value of `mySceneReference.BuildIndex`.
}

The pattern is the standard one: the out parameter carries the value when the call succeeds, and the else branch is where the property would have thrown. The advantage over checking State is that the check and the read happen together, so a reference cannot change state between the two statements, and the code reads as one operation rather than two that have to be kept in sync.

One exception is called out in an important note. TryGetAddress throws AddressablesSupportDisabledException if addressables support is disabled, exactly like the Address property. So the TryGet family is not a guarantee against exceptions in the addressables case, and a project without the addressables package should not wrap that call in a general try and catch expecting a boolean result.

The addressables decision and the editor utilities

Addressables support is enabled or disabled automatically depending on whether the addressables package is present in the project, and the README points at the Addressables Package Documentation for how to install it.

The interesting part is the design note attached to that behaviour. The public API and settings concerning addressables remain visible even when the support is disabled, as a deliberate choice following the principle of least astonishment. The stated reason is that a project which later uninstalls addressables will not face an overwhelming amount of compiler errors, so the transition between using and not using addressables needs only a minimal refactor.

In practice this means a project can start with plain scenes and add addressables later without the entire codebase becoming a compile error in the interim. The cost is that the addressables members are always visible in the API, so a reader of the code has to know whether the current build has the package installed to know whether those members work.

The README also has a section on inline inspector utilities, describing a scene that will be accessible in runtime only under certain conditions, but the section is cut off in the version available here, so the details of those utilities are not documented on this page.

Where Eflatun.SceneReference is the wrong tool

The first limitation is the Unity version floor. The minimum compatible version is 2020.3.48f1, so a project pinned to an older editor cannot use the package at all.

The second is that it does not replace a scene management design. The package resolves references and validates them, but it says nothing about how scenes should be organised, when they should be loaded, or how memory should be handled during a long play session. A project whose real problem is scene loading overhead will find this package answers a different question.

The third is the addressables exception described above. If a project has no addressables package installed, the Address member and TryGetAddress both throw, so the package is not uniformly safe in a project without that package.

The fourth is that the validation surface is a snapshot of the build configuration, not a guarantee. A scene can be in the build when the reference is validated and missing from a later build if a build script changes the scene list, and the reference itself will not notice.

The fifth is the release gap. Recent releases are 5.0.0 from 2026-04-12, then 4.1.1 from 2024-06-16 and 4.1.0 from 2024-06-15. The last push was on 2026-04-12, so the tip of main is at 5.0.0, and a project still on the 4.x line is two years behind the current major version.

How it compares with a hand written scene reference component

The most common alternative is a project-local MonoBehaviour or serializable class that wraps a scene name and validates it in OnValidate. The difference in approach is who owns the validation. A hand written component lives in the project, so it can be extended to fit local rules, but every project writes it, and every project gets it slightly wrong, typically by validating in the editor and forgetting to handle the build configuration.

Eflatun.SceneReference takes the other side of that trade. The state machine, the priority ordering of the unsafe reasons and the TryGet family are decided once, and the code is tested by a single maintainer rather than by each team. The cost is that a project needing behaviour outside the package cannot add it without forking or wrapping.

The second alternative is not doing anything typed at all and using Addressables keys as strings. Where a project loads everything through Addressables, the key is already a stable identifier and the build configuration problem largely disappears, so the package adds less than it does in a build-settings based project.

The third comparison is with Unity's own SerializedReference attribute, which gives type safety for arbitrary serializable objects but does not resolve a scene, validate a build index or report a build membership problem. The package is specifically about scenes and the build configuration around them.

Licence, releases and upgrade cost

The licence is MIT, with the terms in the LICENSE.md file at the root of the repository, so the package can be used in commercial projects and modified.

The package is distributed through OpenUPM, and the version numbers follow the semantic versioning style with major versions such as 5.0.0. The recent releases show a gap between 4.1.1 in June 2024 and 5.0.0 in April 2026, which suggests the 5.0 line came with breaking changes worth reading the CHANGELOG.md for. The repository keeps a changelog file at the root.

The upgrade cost for a user is low as long as the pinned version is used. Because the package is a normal Unity package with a manifest entry, the version travels with the project through source control, and the `upm` tag is available if a project deliberately wants to float, though the README discourages that.

The two things to verify before upgrading are the Unity version requirement, which the 5.0 line may have raised above the 2020.3.48f1 floor stated for the package, and whether the addressables behaviour has changed, since that support is the part of the API most likely to shift between major versions.

Editorial conclusion

Eflatun.SceneReference suits a Unity team that has been storing scene names as strings and paying for it in rename errors and null references at runtime. It is not worth adopting for a project that already uses a typed scene reference of its own or that loads everything through Addressables by key, since the package's value is mostly in validation and in the editor experience. Before installing, check that your project runs Unity 2020.3.48f1 or newer, and decide deliberately whether you want the addressables integration, because the package keeps the addressables API visible even when the support is switched off.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. starikcetin/Eflatun.SceneReference on GitHub