Code reload and the code lifecycle
Understand how and when the Editor reloads parts of your project code, and how your code can hook into the code lifecycle to perform setup and cleanup at key stages.
Read time 5 minutesLast updated 6 days ago
As you develop and iterate in the Unity Editor, your project code is automatically loaded and reloaded as necessary to incorporate changes you make.
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:
- Recompiling script assemblies.
- Serializing managed objects to save their state.
- Unloading or destroying existing script assemblies.
- Reloading script assemblies.
- Deserializing managed objects to restore their state, and performing any necessary initialization.
By default Unity automatically reloads code as part of an Asset Database refresh, when it detects changes to your scripts or other assets.
If you choose to, you can also configure the Editor to reload code on transition between Edit mode and Play mode.
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 namespace, provides a more coherent alternative to an older set of lifecycle APIs that were a mixture of attributes, events, and interfaces.
Unity.Scripting.LifecycleManagementThe 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 Mono 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 namespace, which is accessible both in the Editor and in Player builds. The newer APIs offer the following key advantages:
Unity.Scripting.LifecycleManagement- and
[OnCodeDeinitializing]offer direct access to previously inaccessible phases of the code lifecycle. The closest equivalent in the older APIs was to use[OnCodeUnloading]and manually manage subscriptions.AssemblyReloadEvents.beforeAssemblyReload - executes before assets are fully loaded, making it better for resource pre-allocation than its older counterparts
[OnCodeInitializing],[InitializeOnLoad], and[InitializeOnLoadMethod], which execute after.RuntimeInitializeOnLoad
Lifecycle phase | New API | Older API |
|---|---|---|
| Serialization of managed objects during code reload. | | No pre-existing equivalent. |
| Before code is unloaded for a code reload. | | |
After assemblies are loaded and initialized. This happens:
| | No pre-existing equivalent. |
After restoring (deserializing) managed objects following a code reload. At this point:
| | |
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 and 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 :
UnityEditor.Scripting.LifecycleManagementUnityEngineEditorApplication.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 namespace, you don't have to use preprocessor directives to exclude them from compilation in Player scripts.
UnityEngine
Lifecycle phase | New API | Older API |
|---|---|---|
On initializing or re-initializing Play mode, which happens:
| | |
On shutting down Play mode, which happens:
| | |
On initialization or re-initialization of Edit mode, which happens:
| | |
On shutting down Edit mode, which happens:
| | |
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.