Code reload and the code lifecycle

As you develop and iterate in the Unity Editor, your project code is automatically loaded and reloaded as necessary to incorporate changes you make, or to handle context transitions, such as switching between Edit mode and Play mode.

This process is referred to in general as code reload, and as domain reload in the context of the Mono scripting backend. Code reload involves the following key phases:

1. Recompiling script assemblies.
2. Serializing managed objects to save their state.
3. Unloading or destroying existing script assemblies.
4. Reloading script assemblies.
5. Deserializing managed objects to restore their state, and performing any necessary initialization.

By default Unity automatically reloads code in the following cases:

• As part of an Asset Database refresh, when Unity detects changes to your scriptsA piece of code that allows you to create your own Components, trigger game events, modify Component properties over time and respond to user input in any way you like. More info
  See in Glossary or other assets.
• On transition between Edit mode and Play mode, to replace Editor scriptsC# source files composed entirely of code that runs in the Unity Editor only and not in the runtime Player build. Keep such scripts in dedicated Editor assemblies either by placing them in a parent folder called Editor or creating an Editor-only assembly definition.
  See in Glossary with runtime scripts, or the other way around.

Accessing the code lifecycle

During the period of its availability, code is loaded, initialized, executed, decommissioned, and unloaded or destroyed. This sequence of stages through which code transitions is referred to as the code lifecycle.

Sometimes it can be necessary to execute code at specific stages of the code lifecycle. For example, to perform appropriate setup or cleanup work at key points prior to or following the loading or unloading of script assemblies, or on transition between Edit mode and Play mode.

Unity enables this by providing public lifecycle APIs that allow your code to receive callbacks at specific points in the code lifecycle.

Lifecycle APIs

A set of public attributes, mostly in the Unity.Scripting.LifecycleManagement namespace, provides a more coherent alternative to an older set of lifecycle APIs that were a mixture of attributes, events, and interfaces.

The new APIs include callbacks for stages of the code lifecycle that were not previously accessible to user code. While some older APIs are bound to MonoA scripting backend used in Unity. More info
See in Glossary and domain reload, the new APIs are guaranteed to work with any future scripting runtimes and code reload mechanisms.

The new APIs are also symmetrical. For each callback on loading code or entering a state, there is a corresponding one for unloading code or exiting the state. The new APIs are also available in the Editor and the Player where necessary.

The tables in the following sections list the new lifecycle APIs alongside older APIs with equivalent functionality and timings in the code lifecycle. It’s recommended to adopt the newer APIs in new code.

Code reload callbacks

The following APIs allow you to receive callbacks at key stages of the code reload process. The new APIs are in the Unity.Scripting.LifecycleManagement namespace, which is accessible both in the Editor and in Player builds. The newer APIs offer the following key advantages:

• [OnCodeDeinitializing] and [OnCodeUnloading] offer direct access to previously inaccessible phases of the code lifecycle. The closest equivalent in the older APIs was to use AssemblyReloadEvents.beforeAssemblyReload and manually manage subscriptions.
• [OnCodeInitializing] executes before assets are fully loaded, making it better for resource pre-allocation than its older counterparts [InitializeOnLoad], [InitializeOnLoadMethod], and RuntimeInitializeOnLoad, which execute after.

For more information and usage examples, refer to the API references for these attributes.

For details of the relative execution order of these callbacks in the context of code reload, refer to Domain and scene reload execution order reference.

Play mode and Edit mode transition callbacks

The following APIs allow you to receive callbacks on entry to and exit from Edit mode and on entry to and exit from Play mode. The newer APIs are in the UnityEditor.Scripting.LifecycleManagement and UnityEngine namespaces respectively. They are two symmetrical attribute pairs that correspond to entry to and exit from Edit mode and entry to and exit from Play mode. They offer two key advantages over the older EditorApplication.playModeStateChange:

• As attributes rather than events, they avoid the overhead and risks of subscribing to events, filtering on enum values, and subscription leaks.
• As the entering and exiting Play mode callbacks are in the UnityEngine namespace, you don’t have to use preprocessor directives to exclude them from compilation in Player scripts.

For more information and usage examples, refer to the API references for these attributes.

For an example of using these APIs to reset static state on entering and exiting Play mode, refer to Resetting state from code.

Additional resources

• Configuring how Unity enters Play mode
• Enter Play mode without domain reload