Unity uses its own serialization system, designed to operate efficiently at runtime. Because of this, serialization in Unity behaves differently to serialization in other programming environments. This page describes the conditions that fields and types must meet for Unity to serialize them.
The following principles apply to Unity serialization:
[Serializable] and [NonSerialized] attributes, but their behavior is subject to the additional Unity-specific rules described in the following sections.UnityEngine.Object. You only need to apply [Serializable] to custom classes or structs used as fields in Unity objects.[Serializable] attribute is not inherited by subclasses. You must apply it to each class in an inheritance hierarchy. Unity does not require [Serializable] on system base classes (such as System.Object) that you can’t modify. For other non-modifiable base classes, such as types from third-party libraries, use [MakeSerializable] to include them in the serialization hierarchy.[NonSerialized] excludes a field from both serialization and the InspectorA Unity window that displays information about the currently selected GameObject, asset or project settings, allowing you to inspect and edit the values. More info[HideInInspector].Serializers in Unity work directly on the fields of your C# classes rather than their properties, so Unity only serializes your fields if they meet certain conditions.
To use field serialization you must ensure that the field:
public, or has a [SerializeField] attribute
private fields are serialized. For more information, refer to Hot reloading.static
const
readonly
[Serializable] attribute.[Serializable] attribute. (Refer to Serialization of custom classes).List<T> of a field type listed above.
Note: With default inline serialization, if the same element appears in a collection twice, the serialized collection contains two separate copies rather than two references to the same object. To preserve multiple references to the same object, use [SerializeReference].
Note: Unity doesn’t support serialization of multilevel types (multidimensional arrays, jagged arrays, dictionaries, and nested container types). If you want to serialize these, you have two options:
The following example demonstrates a common mistake where [Serializable] is missing from a custom class:
// INCORRECT: Missing [Serializable] — Unity won't serialize PlayerStats
public class PlayerStats
{
public int health;
public int mana;
}
public class Player : MonoBehaviour
{
public PlayerStats stats; // This field won't be serialized
}
To make the class serializable, add the [Serializable] attribute:
// CORRECT: PlayerStats is now serializable
[System.Serializable]
public class PlayerStats
{
public int health;
public int mana;
}
public class Player : MonoBehaviour
{
public PlayerStats stats; // Serialized correctly
}
For more examples and compile-time detection of serialization issues, refer to the serialization rules analyzer.
For Unity to serialize a custom class, you must ensure the class:
[Serializable] attribute.When you assign an instance of a UnityEngine.Object-derived class to a field and Unity saves that field, Unity serializes the field as a reference to that instance. Unity serializes the instance itself independently, so it isn’t duplicated when multiple fields are assigned to the instance. But for custom classes which don’t derive from UnityEngine.Object, Unity includes the state of the instance directly in the serialized data of the MonoBehaviour or ScriptableObject that references them. There are two ways that this can happen: inline and by [SerializeReference].
[SerializeReference] on the field that references the class. This means that if you store a reference to an instance of a custom class in several different fields, they become separate objects when serialized. Then, when Unity deserializes the fields, they contain different distinct objects with identical data.[SerializeReference] serialization: If you do specify [SerializeReference], Unity establishes the object as a managed reference. The host object still stores the objects directly in its serialized data, but in a dedicated registry section.
Important: You can use [SerializeReference] only on fields with reference types (classes). You cannot use it on value types such as structs, enums, or primitive types (int, float, etc.). Value types are always serialized inline and cannot be serialized by reference.
[SerializeReference] adds some overhead but supports the following cases:
[SerializeReference], they become separate objects when serialized.[SerializeReference] Unity only serializes the fields that belong to the parent class. When Unity deserializes the class instance, it instantiates the parent class instead of the derived class.
Note: Inline serialization is more efficient, and you should use it unless you specifically need one of the features that [SerializeReference] supports. For full details on how to use [SerializeReference], refer to the SerializeReference documentation.
When you use [SerializeReference], Unity doesn’t strictly enforce [Serializable], but displays a warning in the Console if a class isn’t marked [Serializable]. You can suppress this warning with the [MakeSerializable] attribute.
When using inline serialization (without [SerializeReference]), Unity handles cycles as follows:
For direct self-references, Unity silently ignores the field. For indirect cycles, Unity logs a warning indicating that the serialization depth limit is exceeded and discards the remaining data. Use [SerializeReference] on the relevant fields to correctly serialize data structures with cycles. For compile-time detection of cycle issues, refer to analyzer rules UAC1005 through UAC1008.
Unity doesn’t serialize properties. However, if the property is backed by a field, the field can be serialized.
public int MyInt
{
get => m_backing;
private set => m_backing = value;
}
[SerializeField] private int m_backing;
field: prefix on attributes for the property. For example:// Serialize the implicit backing field behind this property
[field: SerializeField]
public int MyInt { get; set; }
// Serialize the implicit backing field behind this property as a reference instead of inline
[field: SerializeReference]
public MyType MyReferenceToType { get; set;}
// Do not serialize the backing field for this property even when hot-reloading
[field: NonSerialized]
public bool NeverSerializedProperty { get; set;}
Unity skips fields that don’t follow its serialization rules, often without producing a visible error, which can cause unexpected data loss. To avoid the most common problems, follow these practices:
[Serializable] to every custom class and struct you intend to serialize. This applies to both inline serialization and [SerializeReference].[Serializable]. The attribute isn’t inherited, so each class must be explicitly marked.[SerializeReference] for complex relationships. If your data structure involves null references, polymorphism, shared references, or cycles, use [SerializeReference] instead of inline serialization.[SerializeReference], direct self-reference cycles cause Unity to ignore the field entirely, and indirect cycles are serialized with a 10-level recursion limit. Use indices, IDs, or [SerializeReference] to avoid these issues.[SerializeReference] on value types. Structs, primitives, and enums are always serialized inline. [SerializeReference] only works with reference types (classes).The serialization rules analyzer detects these issues at compile time and provides real-time feedback in your IDE.