Disclaimer (2022)
This project is no longer being actively maintained, and should be considered archived.
If you do find it useful you are absolutely encouraged to fork it and feel free to reach out so your work can be linked to from here.
Here are some relevant projects to check out:
This repository has UPM support. You can install this plugin to your project using OpenUPM:
npm install -g openupm-cli
openupm add com.johannesmp.unityscenereference
What is this?
A SceneReference wrapper class that uses ISerializationCallbackReceiver and a custom PropertyDrawerto provide safe, user-friendly scene references in scripts.
Why is this needed?
Sooner or later Unity Developers will want to reference a Scene from script, so they can load it at runtime using the SceneManager.
We can store a string of the scene's path (as the SceneAsset documentation suggests), but that is really not ideal for production: If the scene asset is ever moved or renamed, then our stored path is broken.
Unity has already solved this problem for assets using Object references. Using AssetDatabasse you can find the path for a given asset. The problem there unfortunately is that we don't have access to AssetDatabase at runtime, since it is part of the UnityEditor Assembly.
So to be able to reliably use a scene both in editor and at runtime we need two pieces of serialized information: A reference to the SceneAsset object, and a string path that can be passed into SceneManager at runtime.
We can create our own Wrapper class that uses ISerializationCallbackReceiver to ensure that the stored path is always valid based on the specified SceneAsset Object.
This SceneReference class is an example implementation of this idea.
Key features
- Custom PropertyDrawer that displays the current Build Settings status, including BuildIndex and convenient buttons for managing it with destructive action confirmation dialogues.
- If (and only if) the serialized Object reference is invalid but the path is still valid (for example if someone merged incorrectly) will recover object using path.
- Buttons collapse to smaller text if full text cannot be displayed.
- Include detailed tooltips and respects Version Control if build settings are not checked out (tested with Perforce).
- It's a single drop-in script. You're welcome to split the Editor-only PropertyDrawer and helpers into their own Editor scripts if you'd like, just for convenience I've put it all in one self-contained file here.
For easy runtime verification I've also provided a testing Monobehaviour that lets you view and load scenes via buttons when in playmode:
Acknowledgements
- This Project was originally created as a github gist by JohannesMP and then moved to this Github Repo
- Special thanks to Starikcetin for contributing and continuing to maintain this project while I was unable to do so. Definitely check out their own implementation at Eflatun.SceneReference!
- Thank you also for contributions from der-hugo, hbollon, joaoborks, NibbleByte and LingDar