serialization-safety

name	serialization-safety
description	Unity serialization rules — FormerlySerializedAs on renames, SerializeField vs public, SerializeReference for polymorphism, Unity null check (== null not ?.). CRITICAL: prevents silent data loss.
alwaysApply	true

Serialization Safety

This is the single most important skill. Serialization mistakes cause silent data loss — every configured value in every scene, prefab, and ScriptableObject resets to default with zero warning.

Rule 1: FormerlySerializedAs on ANY Rename

// BEFORE: field is called _speed
[SerializeField] private float _speed = 5f;

// AFTER: renaming to _moveSpeed — MUST add FormerlySerializedAs
[FormerlySerializedAs("_speed")]
[SerializeField] private float _moveSpeed = 5f;

Why: Unity serializes fields by name. Renaming breaks the name → value mapping. Every scene, prefab, and SO that configured this field silently loses its value. [FormerlySerializedAs] tells Unity "this field used to be called X."

The attribute stays forever. Never remove it.

Rule 2: Unity Null Check

// CORRECT — Unity overrides == to detect destroyed objects
if (_target == null) return;
if (_target != null) _target.TakeDamage(10);

// WRONG — bypasses Unity's destroyed-object detection
if (_target is null) return;        // C# null check, misses destroyed
_target?.TakeDamage(10);            // ?. bypasses Unity ==, calls on destroyed
_target ??= FindNewTarget();        // ??= uses C# null, not Unity null

Why: Unity objects can be "destroyed" (C++ side freed) but not yet garbage collected (C# reference still exists). Unity overrides == to return true for destroyed objects. C# pattern matching (is null, ?., ??) uses reference equality, which returns false — so you call methods on destroyed objects, causing crashes or undefined behavior.

Rule 3: What Unity Serializes

Serialized:

• public fields (without [NonSerialized])
• [SerializeField] private/protected fields
• Types: int, float, bool, string, Vector2/3/4, Color, Rect, Quaternion, AnimationCurve, Gradient, enums, UnityEngine.Object subclasses, arrays, List<T>, [Serializable] structs/classes

NOT Serialized:

• Properties (getters/setters) — even with [SerializeField]
• static fields
• readonly fields
• const fields
• Dictionary<K,V> — use ISerializationCallbackReceiver
• Interfaces / abstract types — use [SerializeReference]
• Delegates / events

Rule 4: SerializeField Private Over Public

// GOOD — controlled exposure
[SerializeField] private float _health = 100f;
public float Health => _health; // Read-only access

// BAD — anyone can modify, clutters API
public float health = 100f;

Rule 5: SerializeReference for Polymorphism

// Without SerializeReference: Unity serializes as base type, losing derived data
[SerializeField] private IAbility _ability; // ERROR: interfaces not serialized

// With SerializeReference: polymorphic serialization
[SerializeReference] private IAbility _ability; // Works: stores concrete type

Rule 6: NonSerialized for Cached Data

public class Enemy : MonoBehaviour
{
    [SerializeField] private float _maxHealth = 100f;

    [NonSerialized] public float CurrentHealth; // Runtime-only, not saved
    
    private Transform _cachedTransform; // Private non-serialized by default (good)
}

Rule 7: ISerializationCallbackReceiver for Dictionaries

public class DataStore : MonoBehaviour, ISerializationCallbackReceiver
{
    // Unity serializes these lists
    [SerializeField] private List<string> _keys = new();
    [SerializeField] private List<float> _values = new();

    // Runtime dictionary (not serialized directly)
    private Dictionary<string, float> _data = new();

    public void OnBeforeSerialize()
    {
        _keys.Clear();
        _values.Clear();
        foreach (KeyValuePair<string, float> pair in _data)
        {
            _keys.Add(pair.Key);
            _values.Add(pair.Value);
        }
    }

    public void OnAfterDeserialize()
    {
        _data = new Dictionary<string, float>();
        for (int i = 0; i < _keys.Count; i++)
        {
            _data[_keys[i]] = _values[i];
        }
    }
}

Rule 8: Serialization Depth Limit

Unity stops serializing at 7 levels of nesting. Deeply nested data structures are silently truncated. If you need deep data, flatten it or use [SerializeReference].

Rule 9: HideInInspector vs NonSerialized

• [HideInInspector] — hides from Inspector but still serializes (data is saved)
• [NonSerialized] — prevents serialization entirely (data is not saved, resets on play)

Rule 10: Auto-Property Serialization

// C# 7.3+ syntax for serialized auto-properties
[field: SerializeField] public float Speed { get; private set; }

// Note: FormerlySerializedAs uses the backing field name:
[field: FormerlySerializedAs("<Speed>k__BackingField")]
[field: SerializeField] public float MoveSpeed { get; private set; }