Serialization best practices

Apply the following coding practices and organizational principles to prevent errors and optimize serialization performance in your project.

Thread safety

Most Unity APIs can only be called from the main thread. Don’t call Unity APIs from constructors and field initializers of serializable types because these run on a separate loading thread.

In development buildsA development build includes debug symbols and enables the Profiler. More info
See in Glossary, Unity throws an error if you attempt to call main thread APIs from a loading thread. In a release build, the code runs without errors but can produce crashes and other unexpected behavior in your application.

Tip: To reduce the risk of errors during serialization, don’t call API methods that can influence the project state or that involve other Unity objects. APIs that are safe to call include Debug.Log and those that work on simple data types, such as math functions and Vector3.

Finalizers

Don’t initiate serialization from finalizer methods. Finalizers don’t run on the main thread. The garbage collector determines when they run and in some circumstances they might not run at all.

Attempting to serialize data from a finalizer can lead to unexpected behavior and crashes. For more information, refer to the Microsoft documentation on Finalizers.

Organizing your data

You can organize your data as follows to ensure optimal use of Unity’s serialization:

• Aim to have Unity serialize the smallest possible set of data. The purpose of this isn’t to save space on your computer’s hard drive, but to make sure that you can maintain backwards compatibility with previous versions of the project. Backwards compatibility can become more difficult later on in development if you work with large sets of serialized data.
• Never have Unity serialize duplicate data or cached data. This causes significant problems for backwards compatibility: it carries a high risk of error because data can get out of sync.
• Use caution when adding fields that reference custom C# classes or structs. When you reference custom C# classes or structs in fields, Unity embeds the whole content of the referenced object in the serialized data of the referencing object. If this structure becomes complex or deeply nested then it can be hard to migrate this data as you change your structure in the future. Also the data from an object can easily be repeated unintentionally more than once in the serialized data. Instead, aim to keep the structure within your MonoBehaviour and ScriptableObject derived classes flat and simple.
• The way to share data between Objects is to use ScriptableObjects. When you reference a class derived from UnityEngine.Object (such as a class derived from ScriptableObject), Unity only serializes the reference and not the entire object graph. So the data is only serialized once, in the ScriptableObject, not at each point that references it. Similarly, you can use the [SerializeReference] attribute if you want to reference the same custom C# class more than once within a single MonoBehaviour or ScriptableObject. For more information, refer to Serialization of custom classes.

Clean up stale serialized data

When you change the structure of a script or a prefabAn asset type that allows you to store a GameObject complete with components and properties. The prefab acts as a template from which you can create new object instances in the scene. More info
See in Glossary, Unity doesn’t immediately rewrite every asset that already references the old structure. Existing serialized data stays on disk until the affected asset is saved again. As a result, assets can accumulate stale serialized data: fields and placeholder objects that no longer correspond to anything in the current project.

How stale data accumulates

Stale data commonly appears in .unity, .prefab, and .asset files in the following ways:

• Removed serialized fields: If you remove a [SerializeField] field from a MonoBehaviour or ScriptableObject script, any asset that previously assigned a value to that field still contains the value in its YAML data. The value is invisible at runtime because the field no longer exists in the class, but it remains on disk until the asset is saved again.
• Stripped placeholders for nested prefab objects: When a sceneA Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More info
  See in Glossary or another prefab references an object inside a nested prefab instance, Unity adds a stripped placeholder object to the containing file. If the referenced object is later removed from the source prefab, the placeholder remains in the containing file until that file is saved again.
• Unused prefab overrides: When a script field referenced by a prefab override is renamed or deleted, the override entry on the prefab instance becomes unused. For information on how to remove unused overrides specifically, refer to Remove unused override data.

Why Unity doesn’t automatically remove stale data

Unity intentionally leaves stale data in place rather than removing it on every script or prefab change for two reasons:

• Performance: Removing it would require Unity to load, modify, and save every asset that depends on the changed script or prefab. For large projects this can mean rewriting thousands of files for a single edit.
• Data recovery: Unity preserves stale data so you can reverse a temporary removal without losing values. For example:
  • If you delete a serialized field and add it back with the same name, the previously serialized values reattach automatically.
  • If you delete a referenced asset and restore it together with its .meta file (so the GUID is unchanged), references to it remain valid.

To preserve data when you rename a field instead of removing it, use the [FormerlySerializedAs] attribute.

Reserialize affected assets

To remove stale data from a single asset, modify any property on the asset in the Editor and save it. This forces Unity to rewrite the asset using the current 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, prefabs, and asset references, dropping any data that no longer corresponds to a field or referenced object.

To clean up stale data across many assets, call the AssetDatabase.ForceReserializeAssets method from an Editor script. The following example reserializes every asset in the project from a menu item:

using UnityEditor;

public static class StaleDataCleanup
{
    [MenuItem("Tools/Reserialize All Assets")]
    static void ReserializeAll()
    {
        AssetDatabase.ForceReserializeAssets();
    }
}

Without arguments, AssetDatabase.ForceReserializeAssets reserializes every asset in the project. To reserialize a specific subset, pass a list of asset paths and an optional ForceReserializeAssetsOptions value to control whether the assets, their .meta files, or both are rewritten.

Important: AssetDatabase.ForceReserializeAssets only runs from direct user actions, such as a menu item. Unity throws an exception if you call it from a Unity callback such as OnEnable (which can run while a scene is being modified), while the Editor is in Play mode, or during a domain reload.

Reserializing many assets at once produces a large set of file changes. Coordinate with your team and your version controlA system for managing file changes. You can use Unity in conjunction with most common version control tools, including Perforce, Git, Mercurial and PlasticSCM. More info
See in Glossary system before running it across a project.

Additional resources

• Serialization rules
• How Unity uses serialization
• JSONSerialization
• Remove unused override data
• AssetDatabase.ForceReserializeAssets