Documentation

Unity Engine

User Manual

Script Reference

Unity Engine

DontDestroyOnLoad(Object)

Do not destroy the target Object when loading a new Scene.
Read time 3 minutesLast updated 6 days ago

Definition

  • Type: Method
  • Namespace: UnityEngine
  • Assembly: UnityEngine.CoreModule
public static void DontDestroyOnLoad(Object target)

Parameters

target

Object
An Object not destroyed on Scene change.

Remarks

The load of a new Scene destroys all current Scene objects. Call Object.DontDestroyOnLoad to preserve an Object during scene loading. If the target Object is a component or GameObject, Unity also preserves all of the Transform’s children. Object.DontDestroyOnLoad only works for root GameObjects or components on root GameObjects. Object.DontDestroyOnLoad does not return a value.
The following example script uses Object.DontDestroyOnLoad. The example has scene1 which starts playing background music from an AudioSource. The music continues when scene2 loads. Switch between scenes using a button.
To implement this example, create two new Scenes, named scene1 and scene2. Open scene1 and add the 
SceneSwap.cs
script to an empty GameObject and name it Menu. Next, add 
DontDestroy.cs
to a new GameObject and name it BackgroundMusic. Add an AudioSource to BackgroundMusic - 
Add Component > Audio > Audio Source
- and import an AudioClip into your Project. Assign the AudioClip to the AudioSource’s AudioClip field. Create a tag, call it music, and add it to BackgroundMusic. Switch to scene2. Again add 
SceneSwap.cs
to a new GameObject and name it Menu. Save the Project. Return to scene1 and run the Project from the Editor.
SceneSwap.cs
script:
using UnityEngine;using UnityEngine.SceneManagement;// Object.DontDestroyOnLoad example.//// Two scenes call each other. This happens when OnGUI button is clicked.// scene1 will load scene2; scene2 will load scene1. Both scenes have// the Menu GameObject with the SceneSwap.cs script attached.//// AudioSource plays an AudioClip as the game runs. This is on the// BackgroundMusic GameObject which has a music tag.  The audio// starts in AudioSource.playOnAwake. The DontDestroy.cs script// is attached to BackgroundMusic.public class SceneSwap : MonoBehaviour{    private void OnGUI()    {        int xCenter = (Screen.width / 2);        int yCenter = (Screen.height / 2);        int width = 400;        int height = 120;        GUIStyle fontSize = new GUIStyle(GUI.skin.GetStyle("button"));        fontSize.fontSize = 32;        Scene scene = SceneManager.GetActiveScene();        if (scene.name == "scene1")        {            // Show a button to allow scene2 to be switched to.            if (GUI.Button(new Rect(xCenter - width / 2, yCenter - height / 2, width, height), "Load second scene", fontSize))            {                SceneManager.LoadScene("scene2");            }        }        else        {            // Show a button to allow scene1 to be returned to.            if (GUI.Button(new Rect(xCenter - width / 2, yCenter - height / 2, width, height), "Return to first scene", fontSize))            {                SceneManager.LoadScene("scene1");            }        }    }}
DontDestroy.cs
script:
using System.Collections;using System.Collections.Generic;using UnityEngine;// Object.DontDestroyOnLoad example.//// This script example manages the playing audio. The GameObject with the// "music" tag is the BackgroundMusic GameObject. The AudioSource has the// audio attached to the AudioClip.public class DontDestroy : MonoBehaviour{    void Awake()    {        GameObject[] objs = GameObject.FindGameObjectsWithTag("music");        if (objs.Length > 1)        {            Destroy(this.gameObject);        }        DontDestroyOnLoad(this.gameObject);    }}