Documentation

Unity Engine

User Manual

Script Reference

Unity Engine

Serialization rules

Conditions that determine whether fields in your scripts are serialized.
Read time 8 minutesLast updated 12 days ago
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.

Key principles

The following principles apply to Unity serialization:
  • Unity serializes fields of your C# classes rather than their properties. Refer to Serialization of properties for details.
  • Unity supports the standard .NET 
    [Serializable]
     and 
    [NonSerialized]
     attributes, but their behavior is subject to the additional Unity-specific rules described in the following sections.
  • Unity automatically serializes built-in types that inherit from 
    UnityEngine.Object
    . You only need to apply 
    [Serializable]
    to custom classes or structs used as fields in Unity objects.
  • The 
    [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 Inspector. To hide a field in the Inspector without preventing serialization, use 
    [HideInInspector]
    .

Field serialization rules

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:
  • Is 
    public
    , or has a 
    [SerializeField]
     attribute
    • Note
      In some cases 
      private
      fields are serialized. For more information, refer to Hot reloading.
  • Is not 
    static
  • Is not 
    const
  • Is not 
    readonly
  • Has a field type that can be serialized:
    • Primitive data types (int, float, double, bool, string, etc.).
    • Enum types (32 bits or smaller).
    • Fixed-size buffers.
    • Unity built-in types, for example, Vector2, Vector3, Rect, Matrix4x4, Color, AnimationCurve.
    • Custom structs with the 
      [Serializable]
      attribute.
    • References to objects that derive from UnityEngine.Object.
    • Custom classes with the 
      [Serializable]
      attribute. (Refer to Serialization of custom classes).
    • An array or 
      List<T>
      of a field type listed above.
    • Dictionary<TKey, TValue>
      with a 
      [SerializeField]
      attribute. Refer to Dictionary serialization.
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 multidimensional arrays, jagged arrays, or collections nested directly in another collection (for example, 
List<Dictionary<string, int>>
or 
Dictionary<string, int>[]
). If you need to serialize such a structure, 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 PlayerStatspublic 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.

Serialization of custom classes

For Unity to serialize a custom class, you must ensure the class:
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]
.
  • Inline serialization: By default, Unity serializes custom classes inline by value when you don't specify 
    [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:
  • Null fields. Inline serialization can't represent null. Instead, it replaces null with an inline object that has unassigned fields.
  • Shared references. If you store a reference to an instance of a custom class in several different fields without using 
    [SerializeReference]
    , they become separate objects when serialized.
  • Graphs and cyclical data (for example, an object that has a reference back to itself). Inline serialization duplicates the full object graph by value, so it can't represent cycles. Refer to Serialization cycles for details.
  • Polymorphism. If you create a class that derives from a parent class and assign it to a field that uses the parent class as its type, without 
    [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.
  • Stable identifiers for pointing to a specific object without hard-coding the object's array position or searching the entire array. Refer to Serialization.ManagedReferenceUtility.SetManagedReferenceIdForObject.
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.

Serialization cycles

When using inline serialization (without 
[SerializeReference]
), Unity handles cycles as follows:
  • Direct self-reference (a class contains a field of its own type): Unity ignores the class entirely during serialization. Any field of this type is always null after deserialization.
  • Indirect cycles (for example, A > B > A): Unity serializes the structure but stops after 10 levels of recursion and discards the remaining data.
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.

Serialization of properties

Unity doesn't serialize properties. However, if the property is backed by a field, the field can be serialized.
  • If a property has an explicit backing field, Unity serializes it according to regular serialization rules. For example:
public int MyInt{get => m_backing;private set => m_backing = value;}[SerializeField] private int m_backing;
  • If a property is an auto-property, then a private backing field is generated for it implicitly by the compiler, and the regular serialization rules apply to this backing field. You can apply attributes to this field by using the 
    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;}

Avoid common serialization issues

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:
  • Add 
    [Serializable]
    to every custom class and struct you intend to serialize.     This applies to both inline serialization and 
    [SerializeReference]
    .
  • Mark every class in an inheritance hierarchy with 
    [Serializable]
    .     The attribute isn't inherited, so each class must be explicitly marked.
  • Use 
    [SerializeReference]
    for complex relationships.     If your data structure involves null references, polymorphism, shared references, or cycles, use 
    [SerializeReference]
    instead of inline serialization.
  • Avoid cycles in inline serialization. Without 
    [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.
  • Don't use 
    [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.

Additional resources