What Is The Correct Terminology For Prefab Mode Scenes And Stages?

Unity Engine
1

I have just discovered the concept of Stages in Unity, and have been making some notes of my own about them to help consolidate in my mind what their role and intended purpose is in Unity.

In particular, it seems that the most common scenario in which we run into Stages is when we open a Prefab Asset and take the Editor into Prefab Mode. As I understand it, this creates what I have been calling a “Preview Stage”, as opposed to the “Main Stage” in which we typically edit Scenes for our Project.

Following on from that, is it correct to say that when we go into Prefab Mode like this the Editor creates a “Preview Scene” in that Preview Stage?

Next, there is the more unique case where we have a Scene in the Main Stage that contains a Prefab Instance. We then use this Scene and Prefab Instance to enter Prefab Mode in context. This again opens a Preview Stage I believe, as indicated by the breadcrumbs at the top of the Scene view.

However, is the Preview Scene in this case a new Scene that is copied from the original Main Stage scene, or is it more accurate to say this is the exact same Scene, simply opened in a different Stage?

Sorry if this is very pedantic questioning, but in my experience precise terminology and labelling aids understanding.

Bonus questions:

  1. Is it correct to say that there is only ever one Main Stage, and we never swap the Main Stage to be some other Stage instance?
  2. Is it to correct to think that Stages are only really relevant to the Unity Editor, and don’t really have any role in a built Unity Player?
  3. I discovered the concept of Stages through reading about Prefabs, and so as far as I know that is the only place where Stages are relevant. Are there any other common scenarios where Stages play a role in the Unity Editor?

Many thanks!

2

From my understanding:

it correct to say that when we go into Prefab Mode like this the Editor creates a “Preview Scene” in that Preview Stage?

Yes, the PrefabStage type derives from PreviewSceneStage. This is a ScriptableObject that “owns” a PreviewScene. It creates the scene upon “entering” the Stage, and destroys it when closed.

https://docs.unity3d.com/ScriptReference/SceneManagement.PreviewSceneStage.html

However, is the Preview Scene in this case a new Scene that is copied from the original Main Stage scene, or is it more accurate to say this is the exact same Scene, simply opened in a different Stage?

This is just guessing, but my understanding is that the “opened” prefab exists always in a PreviewScene, but when opened in context it does some masking shinanigans to make the SceneView display both the MainStage scene and the PreviewStage scene on top

  1. Is it correct to say that there is only ever one Main Stage, and we never swap the Main Stage to be some other Stage instance?

I believe that yes. The MainStage is always the same, and it holds every “regular” scene (basically, any non-preview scene) that is opened in the editor. You can only ever have 1 “main” scene instance loaded, any “regular” extra scene is “slave” to the main one, but they both are contained within the Stage.

The MainStage class in the CSharpReferenceCode repository
image

  1. Is it to correct to think that Stages are only really relevant to the Unity Editor, and don’t really have any role in a built Unity Player?

Yes, they are an Editor-only concept. Stage is a type defined on UnityEditor.SceneManagement, and is a utility concept designed to group the visual state of the Hierarchy&SceneView Windows, so you can see the currently relevant GameObjects that conform the context you are working on.

  1. I discovered the concept of Stages through reading about Prefabs, and so as far as I know that is the only place where Stages are relevant. Are there any other common scenarios where Stages play a role in the Unity Editor?

i dont know if stages are officially implemented for any other Unity System, but i believe Prefab edition are the reason they exposed them.

The PrefabStage class in CSharpReferenceCode
The PrefabStageUtility class in the CSharpReferenceCode

I’ve personally used them on other occasions to create custom assets. In my case, a custom vegetation-mesh-editor that transformed an “.fbx”-like file into fake different GameObjects with Meshes, so you could assign pivot positions, and wind shinanigans on them, and then re-serialize into the same file. So i would open a PreviewSceneStage - derived type, that would load the created GameObjects so you could edit&save them in a friendly prefab-like manner.

1 Like
3

Alright thanks for your reply! Good to hear that it sounds like I’ve picked up the right ideas.

Your custom preview stage shenanigans sound really impressive. I think that sounds a bit beyond me for the time being, but maybe one day…