serialization-safety

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