EditorSceneManager

Description

Manage scenes in the Editor when it is in Edit mode.

The EditorSceneManager is a scene management system for Edit mode in the Editor. The EditorSceneManager extends the SceneManager and provides Editor-specific logic and behavior on top of SceneManager’s API.

Use the EditorSceneManager to control which scenes are displayed in the Hierarchy window by using OpenScene, CloseScene, or, to open multiple scenes at once, use RestoreSceneManagerSetup.

Note: In Play mode, use the SceneManager API to load and unload scenes.

Terminology:

• SceneAsset is the imported object for scene asset files with the extension ‘.unity’. It is used to set up references to scene files in Editor scripts. Note that SceneAsset is Editor-only, since paths or the index of a scene in the Build Settings is used for loading at runtime.
• Scene is an instance of a scene file when loaded with SceneManager.LoadScene in Play mode or when opened with EditorSceneManager.OpenScene in Edit mode.

When a scene file has been opened by the EditorSceneManager.OpenScene, the contents of the scene file are loaded into memory and a Scene struct handle is returned. This Scene struct is used by various Editor and runtime APIs.

Creating a scene

You can use EditorSceneManager.NewScene to create a new scene. When you create a new Scene, it displays in the Hierarchy as "Untitled". This untitled scene has not yet been saved to disk. You can only have one "Untitled" scene at a time.

Saving a scene to a SceneAsset

These are APIs you can use to save a scene to a SceneAsset on disk at the given path, either directly from code or from a Save dialog:

• EditorSceneManager.SaveScene
• EditorSceneManager.SaveScenes
• EditorSceneManager.SaveOpenScenes
• EditorSceneManager.SaveModifiedScenesIfUserWantsTo

Opening and closing scenes

Use the following to control which scenes are opened in Edit mode and shown in the Hierarchy window:

• EditorSceneManager.OpenScene
• EditorSceneManager.CloseScene
• EditorSceneManager.RestoreSceneManagerSetup

Note: The Editor requires at least one scene to be open and loaded. If you want to close all scenes, use the NewSceneMode.Single with the EditorSceneManager.NewScene API.

Accessing loaded scenes

The EditorSceneManager offers APIs to access the currently loaded scenes through its base class. For example, SceneManager.loadedSceneCount, SceneManager.GetSceneAt, and SceneManager.GetSceneByPath.

Scene manipulation

Use methods through the base SceneManager class, such as SceneManager.MergeScenes and SceneManager.MoveGameObjectToScene, to move objects between scenes.

EditorSceneManager events

The EditorSceneManager also exposes many events that can be used to listen to changes to scenes like: when a new scene is created, or when a scene is opened or closed in the Editor. Scripts can register on these events and then be notified when there are changes in the state of the EditorSceneManager. Refer to the Events section.

Editor tooling scenes

The EditorSceneManager also has the following API to managing in-memory Editor-only tooling scenes. These are called preview scenes and the lifetime of these scenes has to be maintained by you. You can use them for your own Editor tooling. These scenes are not automatically shown in the Hierarchy window.

• EditorSceneManager.NewPreviewScene
• EditorSceneManager.ClosePreviewScene

Controlling the start scene in Play mode

In any Editor script, you can set EditorSceneManager.playModeStartScene if you want to mimic a custom boot scene for Play mode instead of playing the currently opened scenes from Edit mode.

Code sample of core EditorSceneManager APIs

using UnityEngine;
using UnityEditor;
using UnityEditor.SceneManagement;
using UnityEngine.UIElements;
using UnityEditor.UIElements;
using System.Collections.Generic;

public class EditorSceneManagerTestWindow : EditorWindow
{
    private readonly string[] m_ScenePaths = { "Assets/Scene1.unity", "Assets/Scene2.unity", "Assets/Scene3.unity", "Assets/Scene4.unity" };
    private ObjectField[] m_SceneFields;

    [MenuItem("Examples/EditorSceneManager")]
    public static void ShowWindow()
    {
        var window = GetWindow<EditorSceneManagerTestWindow>();
        window.titleContent = new GUIContent("EditorSceneManager APIs");
        window.minSize = new Vector2(300, 400);
    }

    public void CreateGUI()
    {
        var root = rootVisualElement;
        root.style.paddingLeft = root.style.paddingRight = root.style.paddingBottom = root.style.paddingTop = 10;

        // Create buttons
        var createScenesButton = CreateButton("Create Test Scenes", 30, CreateScenes);
        var openSingleSceneButton = CreateButton("Open Single Scene", 10, OpenSingleScene);
        var restoreSceneManagerSetupButton = CreateButton("Restore SceneManager Setup", 10, RestoreSceneManagerSetup);
        var closeAllScenesButton = CreateButton("Close All Scenes", 10, CloseAllScenes);

        // Add buttons to rootVisualElement
        root.Add(createScenesButton);
        root.Add(openSingleSceneButton);
        root.Add(restoreSceneManagerSetupButton);
        root.Add(closeAllScenesButton);

        // Add title
        var titleLabel = new Label("Scene Asset References");
        titleLabel.style.fontSize = 12;
        titleLabel.style.marginBottom = 10;
        titleLabel.style.marginTop = 30;
        titleLabel.style.unityFontStyleAndWeight = FontStyle.Bold;
        root.Add(titleLabel);

        // Add a couple of object fields for picking SceneAssets
        const int kNumObjectFields = 5;
        m_SceneFields = new ObjectField[kNumObjectFields];
        for(int i=0; i<m_SceneFields.Length; i++)
        {
            var sceneField = new ObjectField()
            {
                objectType = typeof(SceneAsset),
                allowSceneObjects = false
            };
            root.Add(sceneField);
            m_SceneFields[i] = sceneField;
        }
      
        var openReferencedScenesButton = CreateButton("Open Referenced Scenes", 10, OpenReferencedScenes);
        root.Add(openReferencedScenesButton);
    }

    private Button CreateButton(string text, float bottomMargin, System.Action clickEvent)
    {
        var button = new Button(clickEvent) { text = text };
        button.style.marginBottom = bottomMargin;
        button.style.height = 30;
        return button;
    }

    private void CreateScenes()
    {
        foreach (var scenePath in m_ScenePaths)
        {
            var scene = EditorSceneManager.NewScene(NewSceneSetup.DefaultGameObjects, NewSceneMode.Single);
            EditorSceneManager.SaveScene(scene, scenePath);
        }
    }

    private void RestoreSceneManagerSetup()
    {
        if (!EditorSceneManager.SaveCurrentModifiedScenesIfUserWantsTo())
            return;

        var sceneSetups = new List<SceneSetup>();
        for (int i = 0; i < m_ScenePaths.Length; i++)
        {
            var scenePath = m_ScenePaths[i];
            var setup = new SceneSetup
            {
                path = scenePath,
                isLoaded = true,
                isActive = (i == 0) // First scene is active
            };
            sceneSetups.Add(setup);
        }

        EditorSceneManager.RestoreSceneManagerSetup(sceneSetups.ToArray());
    }

    private void OpenSingleScene()
    {
        if (!EditorSceneManager.SaveCurrentModifiedScenesIfUserWantsTo())
            return;

        EditorSceneManager.OpenScene(m_ScenePaths[0], OpenSceneMode.Single);
    }

    private void CloseAllScenes()
    {
        if (!EditorSceneManager.SaveCurrentModifiedScenesIfUserWantsTo())
            return;

        EditorSceneManager.NewScene(NewSceneSetup.EmptyScene, NewSceneMode.Single);
    }

    private void OpenReferencedScenes()
    {
        // Check if we have valid scenes
        var sceneSetups = new List<SceneSetup>();
        bool hasValidScenes = false;

        for (int i = 0; i < m_SceneFields.Length; i++)
        {
            var sceneAsset = m_SceneFields[i].value as SceneAsset;
            if (sceneAsset != null)
            {
                hasValidScenes = true;
                var scenePath = AssetDatabase.GetAssetPath(sceneAsset);
                var sceneSetup = new SceneSetup
                {
                    path = scenePath,
                    isLoaded = true,
                    isActive = (i == 0) // First scene is active
                };
                sceneSetups.Add(sceneSetup);
            }
        }

        if (!hasValidScenes)
        {
            EditorUtility.DisplayDialog("Error", "Please assign at least one scene.", "OK");
            return;
        }

        // Save current modified scenes if necessary
        if (!EditorSceneManager.SaveCurrentModifiedScenesIfUserWantsTo())
            return;

        // Restore the scene setup
        EditorSceneManager.RestoreSceneManagerSetup(sceneSetups.ToArray());
    }
}

Static Properties

Static Methods

Events

Delegates

Inherited Members