la classe SceneManager

Gestion des scènes au moment de l'exécution. Des techniques telles que le chargement synchrone et asynchrone de scènes, les effets de transition et les scènes additives sont toutes possibles avec le SceneManager d'Unity. Étonnamment, des scripts complexes de gestion de scènes ne sont pas nécessaires pour implémenter cette fonctionnalité. Les scènes additives sont également très adaptatives et peuvent être utilisées pour charger plusieurs scènes de jeu, scènes de configuration, scènes de débogage et bien d'autres alternatives utiles.

Propriétés statiques

Méthodes statiques

Événements

sceneCount

public static int sceneCount;

Le nombre total de scènes actuellement chargées. Le nombre de scènes actuellement chargées sera retourné.

sceneCountInBuildSettings

public static int sceneCountInBuildSettings;

Nombre de scènes dans le Build Settings. Le nombre de scènes qui ont été ajoutées au Build Settings. L'éditeur contiendra les scènes qui étaient ouvertes avant d'entrer en playmode.

CreateScene

public static SceneManagement.Scene CreateScene(string sceneName);

Paramètres

Retourne

Description

Créer une nouvelle scène vide à l'exécution avec le nom donné.

La nouvelle scène sera ajoutée de manière additive dans la hiérarchie à côté des scènes existantes qui sont actuellement ouvertes. Le chemin de la nouvelle Scène sera vide. Cette fonction sert à créer des scènes lors de l'exécution. Pour créer une scène au moment de l'édition (par exemple, lors de la création d'un script d'éditeur ou d'un outil qui doit créer des scènes), utilisez EditorSceneManager.NewScene.

using UnityEngine.SceneManagement;
using UnityEngine;
using System.Collections;

public class ExampleClass : MonoBehaviour
{
    Scene newScene = SceneManager.CreateScene("Ma nouvelle scène");
}

GetActiveScene

public static SceneManagement.Scene GetActiveScene();

Retourne

Description

Obtient la scène actuellement active. La Scène actuellement active est la Scène qui sera utilisée comme cible pour les nouveaux GameObjects instanciés par des scripts. Notez que la scène active n'a aucun impact sur les scènes rendues.

using UnityEngine;
using UnityEngine.SceneManagement;

public class GetActiveSceneExample : MonoBehaviour
{
    void Start()
    {
        Scene scene = SceneManager.GetActiveScene();
        Debug.Log("La scène active est '" + scene.name + "'.");
    }
}

GetSceneAt

public static SceneManagement.Scene GetSceneAt(int index);

Paramètres

Retourne

Description

Obtient la scène à l'index dans la liste des scènes chargées du SceneManager.

using UnityEditor;
using UnityEngine.SceneManagement;
using UnityEngine;

public class Example
{
    // Ajoute un élément de menu qui donne un bref résumé des Scènes actuellement ouvertes
    [MenuItem("SceneExample/Scene Summary")]
    public static void ListSceneNames()
    {
        string output = "";
        if (SceneManager.sceneCount > 0)
        {
            for (int n = 0; n < SceneManager.sceneCount; ++n)
            {
                Scene scene = SceneManager.GetSceneAt(n);
                output += scene.name;
                output += scene.isLoaded ? " (Loaded, " : " (Not Loaded, ";
                output += scene.isDirty ? "Dirty, " : "Clean, ";
                output += scene.buildIndex >= 0 ? " in build)\n" : " NOT in build)\n";
            }
        }
        else
        {
            output = "Aucune scène ouverte.";
        }
        EditorUtility.DisplayDialog("Scene Summary", output, "Ok");
    }
}

GetSceneByBuildIndex

public static SceneManagement.Scene GetSceneByBuildIndex(int buildIndex);

Paramètres

Retourne

Description

Obtient une structure de scène à partir d'un index de build.

Cette méthode renvoie une scène valide si une scène a été ajoutée au Build settings de l'index de construction donné ET que la scène est chargée. S'il n'a pas encore été chargé, le SceneManager ne peut pas renvoyer une scène valide.

GetSceneByName

public static SceneManagement.Scene GetSceneByName(string name);

Paramètres

Retourne

Description

Cherche dans les scènes chargées, une scène par son nom.

Le nom doit être sans l'extension .unity. Le nom peut être la dernière partie du nom affichée dans la fenêtre BuildSettings, auquel cas la première scène correspondant sera retournée. Le nom peut également être le chemin d'accès tel qu'affiché dans le Build Settings (toujours sans l'extension .unity), auquel cas seule la correspondance exacte sera renvoyée. Ceci est insensible à la casse.

GetSceneByPath

public static SceneManagement.Scene GetSceneByPath(string scenePath);

Paramètres

Retourne

Description

Recherche toutes les scènes chargées pour une scène ayant le chemin d'accès donné.

SceneManager.LoadScene

public static void LoadScene(int sceneBuildIndex, SceneManagement.LoadSceneMode mode = LoadSceneMode.Single);

public static void LoadScene(string sceneName, SceneManagement.LoadSceneMode mode = LoadSceneMode.Single);

Paramètres

Description

Charge la scène par son nom ou son index dans le Build Settings.

Lorsque vous utilisez SceneManager.LoadScene, le chargement ne se fait pas immédiatement, il se termine dans la frame suivante. Ce comportement semi-asynchrone peut provoquer un bégaiement de frame et peut prêter à confusion car la charge ne se termine pas immédiatement.

Étant donné que le chargement est défini pour se terminer dans la prochaine frame rendu, l'appel de SceneManager.LoadScene force toutes les opérations AsynOperations précédentes à se terminer, même si AsyncOperation.allowSceneActivation est défini sur false. Cela peut être évité en utilisant LoadSceneAsync à la place.

Le nom de scène donné peut être soit le nom de la scène, sans l'extension .unity, soit le chemin comme indiqué dans la fenêtre BuildSettings sans l'extension .unity. Si seul le nom de scène est donné, cela chargera la première scène de la liste correspondante. Si vous avez plusieurs Scènes avec le même nom mais des chemins différents, vous devez utiliser le chemin complet.

Notez que sceneName est insensible à la casse, sauf lorsque vous chargez la scène à partir d'un AssetBundle. Pour ouvrir des scènes dans l'éditeur, voir EditorSceneManager.OpenScene.

using UnityEngine;
using UnityEngine.SceneManagement;

public class ExampleClass : MonoBehaviour
{
    void Start()
    {
        // Seule la spécification de sceneName ou sceneBuildIndex chargera la scène avec le mode Single
        SceneManager.LoadScene("AutreScene", LoadSceneMode.Additive);
    }
}

// Charge un assetbundle qui contient des scènes.
// Lorsque l'utilisateur clique sur un bouton, la première scène
// de l'assetbundle est chargée et remplace la scène actuelle.

using UnityEngine;
using UnityEngine.SceneManagement;

public class LoadScene : MonoBehaviour
{
    private AssetBundle myLoadedAssetBundle;
    private string[] scenePaths;

    // Use this for initialization
    void Start()
    {
        myLoadedAssetBundle = AssetBundle.LoadFromFile("Assets/AssetBundles/scenes");
        scenePaths = myLoadedAssetBundle.GetAllScenePaths();
    }

    void OnGUI()
    {
        if (GUI.Button(new Rect(10, 10, 100, 30), "Change Scene"))
        {
            Debug.Log("Scene2 loading: " + scenePaths[0]);
            SceneManager.LoadScene(scenePaths[0], LoadSceneMode.Single);
        }
    }
}

Les deux exemples de script suivants montrent comment LoadScene peut charger des scènes à partir du Build Settings. LoadSceneA utilise le nom de la scène à charger. LoadSceneB utilise le numéro de la scène à charger. Les scripts fonctionnent ensemble.

// SceneA.
// SceneA reçoit le nom sceneName qui chargera SceneB depuis le Build Settings

using UnityEngine;
using UnityEngine.SceneManagement;

public class LoadScenesA : MonoBehaviour
{
    void Start()
    {
        Debug.Log("LoadSceneA");
    }

    public void LoadA(string scenename)
    {
        Debug.Log("sceneName à charger : " + scenename);
        SceneManager.LoadScene(scenename);
    }
}

// SceneB.
// SceneB reçoit le SceneBuildIndex de 0 qui chargera SceneA depuis le Build Settings

using UnityEngine;
using UnityEngine.SceneManagement;

public class LoadScenesB : MonoBehaviour
{
    void Start()
    {
        Debug.Log("LoadSceneB");
    }

    public void LoadB(int sceneANumber)
    {
        Debug.Log("sceneBuildIndex à charger : " + sceneANumber);
        SceneManager.LoadScene(sceneANumber);
    }
}

LoadSceneAsync

public static AsyncOperation LoadSceneAsync(string sceneName, SceneManagement.LoadSceneMode mode = LoadSceneMode.Single);

public static AsyncOperation LoadSceneAsync(int sceneBuildIndex, SceneManagement.LoadSceneMode mode = LoadSceneMode.Single);

Paramètres

Retourne

Description

Charge la scène de manière asynchrone en arrière-plan.

Le nom de scène donné peut être le chemin complet de la scène, le chemin affiché dans la fenêtre Build Settings ou simplement le nom de la scène. Si seul le nom de scène est donné, cela chargera la première scène de la liste correspondante. Si vous avez plusieurs scènes avec le même nom mais des chemins différents, vous devez utiliser le chemin complet de la scène dans le Build Settings.

Exemples de formats pris en charge :

• "Scene1"
• "Scene2"
• "Scenes/Scene3"
• "Scenes/Others/Scene3"
• "Assets/scenes/others/scene3.unity"

using System.Collections;
using UnityEngine;
using UnityEngine.SceneManagement;

public class Example : MonoBehaviour
{
    void Update()
    {
        // Appuyez sur la touche espace pour démarrer la coroutine
        if (Input.GetKeyDown(KeyCode.Space))
        {
            // Utilise une coroutine pour charger la scène en arrière-plan
            StartCoroutine(LoadYourAsyncScene());
        }
    }

    IEnumerator LoadYourAsyncScene()
    {
        // L'application charge la scène en arrière-plan pendant l'exécution de la scène en cours.
        // Ceci est particulièrement utile pour créer des écrans de chargement.
        // Vous pouvez également charger la scène en utilisant sceneBuildIndex. Dans ce cas,
        // Scene2 a un sceneBuildIndex de 1 comme indiqué dans le Build Settings.

        AsyncOperation asyncLoad = SceneManager.LoadSceneAsync("Scene2");

        // Attend que la scène asynchrone se charge complètement
        while (!asyncLoad.isDone)
        {
            yield return null;
        }
    }
}

MergeScenes

public static void MergeScenes(SceneManagement.Scene sourceScene, SceneManagement.Scene destinationScene);

Paramètres

Description

Cela va fusionner la scène source dans la destinationScene.

Cette fonction fusionne le contenu de la scène source dans la scène de destination et supprime la scène source. Tous les GameObjects à la racine de la scène source sont déplacés vers la racine de la scène de destination.

MoveGameObjectToScene

public static void MoveGameObjectToScene(GameObject go, SceneManagement.Scene scene);

Paramètres

Description

Déplace un GameObject de sa scène actuelle vers une nouvelle scène.

Vous ne pouvez déplacer que les GameObjects racine d'une scène à l'autre. Cela signifie que le GameObject à déplacer ne doit pas être un enfant d'un autre GameObject dans sa Scene. Cela ne fonctionne que si les GameObjects sont déplacés vers une scène déjà chargée (additif). Si vous voulez charger des scènes simples, assurez-vous d'utiliser DontDestroyOnLoad sur le GameObject que vous souhaitez déplacer vers une nouvelle scène, sinon Unity le supprime lorsqu'il charge une nouvelle scène.

// Ce script déplace le GameObject que vous attachez dans l'inspecteur à une scène que vous spécifiez dans l'inspecteur.
// Attachez ce script à un GameObject vide.
// Cliquez sur GameObject, allez dans son inspecteur et tapez le nom de la scène que vous voulez charger dans le champ Scène.
// Associez le GameObject que vous souhaitez déplacer à une nouvelle scène dans le champ "My Game Object"

// Assurez-vous que vos scènes sont dans votre Build (File > Build Settings).

using System.Collections;
using UnityEngine;
using UnityEngine.SceneManagement;

public class Example : MonoBehaviour
{
    // Tapez le nom de la scène que vous souhaitez charger dans l'inspecteur
    public string m_Scene;

    // Affectez votre GameObject que vous voulez déplacer la scène dans l'inspecteur.
    public GameObject m_MyGameObject;

    void Update()
    {
        // Appuyez sur la touche espace pour ajouter la scène de manière additive et déplacer le GameObject sur cette scène
        if (Input.GetKeyDown(KeyCode.Space))
        {
            StartCoroutine(LoadYourAsyncScene());
        }
    }

    IEnumerator LoadYourAsyncScene()
    {
        // Défini la scène actuelle pour pouvoir la décharger plus tard
        Scene currentScene = SceneManager.GetActiveScene();

        // L'application charge la scène en arrière-plan en même temps que la scène actuelle.
        AsyncOperation asyncLoad = SceneManager.LoadSceneAsync(m_Scene, LoadSceneMode.Additive);

        // Attend que la dernière opération se charge complètement pour retourner quoi que ce soit
        while (!asyncLoad.isDone)
        {
            yield return null;
        }

        // Déplace le GameObject (vous l'attachez dans l'inspecteur) à la Scene nouvellement chargée
        SceneManager.MoveGameObjectToScene(m_MyGameObject, SceneManager.GetSceneByName(m_Scene));
        // Décharge la scène précédente
        SceneManager.UnloadSceneAsync(currentScene);
    }
}

SetActiveScene

public static bool SetActiveScene(SceneManagement.Scene scene);

Paramètres

Retourne

Description

Régle la scène pour qu'elle soit active.

La Scène active est la Scène qui sera utilisée comme cible pour les nouveaux GameObjects instanciés par des scripts et à partir de quelle scène les réglages d'éclairage sont utilisés. Lorsque vous ajoutez une scène de manière additive (voir LoadSceneMode.Additive), la première scène est toujours conservée en tant que scène active. Utilisez-le pour basculer la Scène active sur la Scène que vous voulez comme cible.

Il doit toujours y avoir une scène marquée comme scène active. Notez que la scène active n'a aucun impact sur les scènes rendues.

// Attachez ce script à un objet GameObject
// Créer 2 boutons (Create > UI > Button)
// Attachez les 2 boutons à l'inspecteur de votre GameObject

// Ce script vous permet de charger une deuxième scène en tant que scène additive.
// Cliquez sur le premier bouton (Load Scene Button) pour charger la scène additive.
// Même si la deuxième scène se charge, la première scène reste la scène active.
// Si vous appuyez sur le deuxième bouton (Set Active Button), il définit la deuxième scène comme la scène active
// (et affiche la scène active actuelle sur la console)


using UnityEngine;
using UnityEngine.SceneManagement;
using UnityEngine.UI;

public class Example : MonoBehaviour
{
    bool m_SceneLoaded;
    public Button m_LoadSceneButton, m_SetActiveButton;

    void Awake()
    {
        // Émet la scène active en cours sur la console
        Debug.Log("Scène active : " + SceneManager.GetActiveScene().name);

        // Vérifie que ce bouton existe
        if (m_LoadSceneButton != null)
        {
            // Récupére le bouton de l'inspecteur. Assurez-vous de définir ceci dans la fenêtre Inspecteur
            Button loadButton = m_LoadSceneButton.GetComponent‹Button>();
            // Appele la fonction LoadScene2Button () lorsque ce bouton est cliqué
            loadButton.onClick.AddListener(LoadSceneButton);
        }

        if (m_SetActiveButton != null)
        {
            Button buttonTwo = m_SetActiveButton.GetComponent‹Button>();
            buttonTwo.onClick.AddListener(SetActiveSceneButton);
        }
    }

    // Charge la scène lorsque vous appuyez sur ce bouton
    void LoadSceneButton()
    {
        // Vérifie que la deuxième scène n'a pas encore été ajoutée
        if (m_SceneLoaded == false)
        {
            // Charge la deuxième scène
            SceneManager.LoadScene("Scene2", LoadSceneMode.Additive);
            // Émet le nom de la scène active en cours.
            // Remarquez qu'il affiche toujours le nom de la première scène.
            Debug.Log("Scène active : " + SceneManager.GetActiveScene().name);
            // La scène a été chargée, quitte cette méthode
            m_SceneLoaded = true;
        }
    }

    // Change la Scène nouvellement chargée en Scène active si elle est chargée
    void SetActiveSceneButton()
    {
        // Autorise l'appui sur cet autre bouton lorsque l'autre bouton a été pressé (la scène 2 est chargée)
        if (m_SceneLoaded == true)
        {
            // Défini Scene2 comme Scène active
            SceneManager.SetActiveScene(SceneManager.GetSceneByName("Scene2"));
            // Voir maintenant que le nom est mis à jour
            Debug.Log("Scène active : " + SceneManager.GetActiveScene().name);
        }
    }
}

UnloadSceneAsync

public static AsyncOperation UnloadSceneAsync(int sceneBuildIndex);

public static AsyncOperation UnloadSceneAsync(string sceneName);

public static AsyncOperation UnloadSceneAsync(SceneManagement.Scene scene);

Paramètres

Retourne

Description

Détruit tous les GameObjects associés à la Scene donnée et supprime la Scene du SceneManager.

Le nom de scène donné peut être le chemin complet de la scène, le chemin affiché dans la fenêtre de Build Settings ou simplement le nom de la scène. Si seul le nom de scène est donné, cela déchargera la première scène de la liste correspondante. Si vous avez plusieurs scènes avec le même nom mais des chemins différents, vous devez utiliser le chemin complet de la scène.

Exemples de formats pris en charge :

• "Scene1"
• "Scene2"
• "Scenes/Scene3"
• "Scenes/Others/Scene3"
• "Assets/scenes/others/scene3.unity"

Ceci est insensible à la casse et du fait qu'il est asynchrone, il n'y a aucune garantie quant au temps d'achèvement. Les assets ne sont actuellement pas déchargés. Afin de libérer de la mémoire d'assets, appelez Resources.UnloadUnusedAssets.

activeSceneChanged

Paramètres

Description

Abonnez-vous à cet événement pour être averti lorsque la scène active a changé.

Ce script ajouté à activeSceneChanged prend deux arguments cachés. Ce sont la scène remplacée et la scène suivante. Les arguments ne sont pas visibles.

Dans l'éditeur, cet événement est envoyé uniquement en mode Lecture (pas en mode Édition). Si l'événement est nécessaire pour le mode Édition, utilisez EditorSceneManager.activeSceneChanged.

// SceneManager.activeSceneChanged
//
// Cet exemple configure Scene1 pour qu'il attende 1,5 seconde avant de passer à Scene2.
// Scene1 est la scène remplacée; Scene2 est la nouvelle scène chargée.

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

public class ScriptExample1 : MonoBehaviour
{
    public delegate void Change();
    public static event Change TimeChanged;

    public void Start()
    {
        SceneManager.activeSceneChanged += ChangedActiveScene;

        // attendre 1,5 secondes avant de passer à Scene2
        StartCoroutine(TimeChangedScene());
    }

    IEnumerator TimeChangedScene()
    {
        print(Time.time + " secondes");
        yield return new WaitForSeconds(1.5f);
        print(Time.time + " secondes");

        // appeler l'événement
        TimeChanged();
    }

    private void ChangedActiveScene(Scene current, Scene next)
    {
        string currentName = current.name;

        if (currentName == null)
        {
            // Scene1 a été supprimé
            currentName = "Remplacé";
        }

        Debug.Log("Scenes: " + currentName + ", " + next.name);
    }

    void OnEnable()
    {
        Debug.Log("OnEnable");
        ScriptExample1.TimeChanged += ChangeScene;
    }

    void ChangeScene()
    {
        Debug.Log("Passage à Scène2");
        SceneManager.LoadScene("Scene2");

        Scene scene = SceneManager.GetSceneByName("Scene2");
        SceneManager.SetActiveScene(scene);
    }

    void OnDisable()
    {
        ScriptExample1.TimeChanged -= ChangeScene;
        Debug.Log("OnDisable s'est produit pour la scène 1");
    }
}

ScriptExample2 annonce simplement que c'est la scène active.

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class ScriptExample2 : MonoBehaviour
{
    void Start()
    {
        Debug.Log("Démarrage de Script2");
    }
}

sceneLoaded

Description

Ajoute un délégué pour obtenir des notifications lorsqu'une scène est chargée. Plutôt que d'être appelé directement, ce code de script montre l'utilisation d'un délégué. Cela signifie que la valeur sceneLoaded est ajoutée dans une liste de délégués.

Dans l'exemple de script ci-dessous, un certain nombre d'appels de méthodes sont affichés. Plus précisément, la première méthode nommée OnEnable() est utilisée pour ajouter OnSceneLoaded(), qui n'est pas une méthode fournie par Unity. Le délégué SceneManager.sceneLoaded peut avoir n'importe quelle méthode connectée et c'est OnSceneLoaded() ici. Enfin, OnDisable() est utilisé pour supprimer OnSceneLoaded() de SceneManager.sceneLoaded.

using UnityEngine;
using UnityEngine.SceneManagement;

public class ExampleCode : MonoBehaviour
{
    // appelé avant tout
    void Awake()
    {
        Debug.Log("Awake");
    }

    // appelé en premier
    void OnEnable()
    {
        Debug.Log("OnEnable appelé");
        SceneManager.sceneLoaded += OnSceneLoaded;
    }

    // appelé en deuxième
    void OnSceneLoaded(Scene scene, LoadSceneMode mode)
    {
        Debug.Log("OnSceneLoaded: " + scene.name);
        Debug.Log(mode);
    }

    // appelé en troisième
    void Start()
    {
        Debug.Log("Start");
    }

    // appelé lorsque le jeu est terminé
    void OnDisable()
    {
        Debug.Log("OnDisable");
        SceneManager.sceneLoaded -= OnSceneLoaded;
    }
}

sceneUnloaded

Description

Ajoute un délégué pour recevoir des notifications lorsqu'une scène a été déchargée. Plutôt que d'être appelé directement, ce code de script montre l'utilisation d'un délégué. Cela signifie que la valeur sceneUnloaded est ajoutée dans une liste de délégués.

Dans l'exemple de script ci-dessous, un appel de méthode est affiché. Plus précisément, une fonction appelée OnSceneUnloaded est ajoutée à sceneUnloaded. SceneUnloaded est appelé lorsque la scène à laquelle il est associé est fermée. À ce stade, SceneUnloaded doit être supprimé de la liste sceneUnloaded.

using UnityEngine;
using UnityEngine.SceneManagement;

public class SceneLoaded1 : MonoBehaviour
{
    public void Start()
    {
        SceneManager.sceneUnloaded += OnSceneUnloaded;
        Debug.Log("Start: SceneLoaded1");
    }

    private void OnSceneUnloaded(Scene current)
    {
        Debug.Log("OnSceneUnloaded: " + current);
    }

    void Update()
    {
        if (Input.GetKey("space"))
        {
            Debug.Log("Quitter Scene1");
            ChangeScene();
        }
    }

    void ChangeScene()
    {
        Debug.Log("Changer pour Scene2");

        SceneManager.LoadScene("Scene2");
    }

    void OnDestroy()
    {
        Debug.Log("OnDestroy");
    }
}

SceneLoaded2 annonce simplement que c'est la scène active.

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class SceneLoaded2 : MonoBehaviour
{
    public void Start()
    {
        Debug.Log("SceneLoaded2");
    }
}