Dictionary serialization

Unity serializes fields declared as Dictionary<TKey, TValue> directly, so you can author dictionary data in scripts and edit it in the Inspector window without writing custom serialization code. The declared field type must be exactly Dictionary<TKey, TValue>.

Dictionary serialization is opt-in: you must apply [SerializeField] to each dictionary field that you want Unity to serialize. Unity only supports certain types as dictionary keys and values. The serialization rules analyzer detects unsupported key and value types at compile time and points to the rule that explains the limitation. The Inspector renders a two-column key/value editor with sort, duplicate-key detection, and column resizing.

Unity serializes a dictionary as a sequence of key/value pairs in insertion order. The order shown in the Inspector is independent of the serialized order. Refer to Sort order in the Inspector.

Declare a serialized dictionary field

You can serialize a dictionary field on a MonoBehaviour, a ScriptableObject, or any nested [Serializable] class or struct. Apply [SerializeField] to a private or a public dictionary field, to make Unity serialize the dictionary:

using System.Collections.Generic;
using UnityEngine;

public class Inventory : MonoBehaviour
{
    [SerializeField]
    private Dictionary<string, int> itemCounts = new Dictionary<string, int>();
}

Public dictionary fields aren’t serialized automatically. Without [SerializeField], Unity skips the field, and the dictionary doesn’t persist across domain reloads, scene saves, or Play mode transitions. The analyzer reports UAC1015 when a public dictionary field is missing [SerializeField], so you can decide whether to opt in or to mark the field [NonSerialized].

[SerializeReference] isn’t valid on dictionary fields, because Unity serializes a dictionary as an inline collection of entries rather than as a polymorphic single reference. The analyzer reports UAC1014 if you apply [SerializeReference] to a dictionary field.

Supported key and value types

Both TKey and TValue must be types that Unity can serialize:

• Primitive types (int, float, double, bool, string).
• Enum types (32 bits or smaller).
• Unity built-in types, such as Vector2, Vector3, Color.
• Custom classes and structs marked [Serializable].
• References to types derived from UnityEngine.Object.

As a key or a value, you can’t use an interface or an abstract type (other than a UnityEngine.Object hierarchy), or a type that isn’t marked [Serializable]. The analyzer reports UAC1012 and UAC1016 respectively.

Collections are valid as values but not as keys:

• As a value, you can use any supported type, or a collection of supported types such as a List<T>, an array, or another Dictionary<TKey, TValue>. For example, Dictionary<int, List<int>> and Dictionary<int, Dictionary<string, int>> are both valid.
• As a key, you can’t use a type that implements IEnumerable - the interface that collection types such as List<T> and arrays implement. The string type is an exception, even though it implements IEnumerable. For example, Unity can’t serialize a Dictionary<List<int>, int> field, because its key type List<int> implements IEnumerable. The analyzer reports UAC1013.

Unity also doesn’t serialize a dictionary that’s nested directly inside another collection. For example, List<Dictionary<string, int>> and Dictionary<string, int>[] aren’t supported. Wrap the dictionary in a [Serializable] class or struct that you can use as the element type. The analyzer reports this case as UAC1009.

Structs that contain a [SerializeReference] field — directly or anywhere in their field graph (including nested structs, class-typed fields, and the inheritance chains of those classes) — cannot be used as either a key or a value in a serialized dictionary. The analyzer reports UAC1019.

Classes that contain a [SerializeReference] field — directly or anywhere in their field graph or inheritance chain — cannot be used as dictionary keys. Classes with [SerializeReference] fields can still be used as dictionary values. The analyzer reports UAC1020.

For the full set of analyzer rules and usage examples, refer to the serialization rules analyzer.

Custom struct and class keys

If you use a custom struct or class as a dictionary key, override GetHashCode and Equals so the dictionary can place and find entries correctly:

• Custom classes without overrides use reference equality. Two instances with identical field values are treated as different keys, which breaks dictionary lookups.
• Custom structs without overrides fall back to reflection-based hashing and equality. The dictionary works correctly but is slow. Add overrides for better performance.
• Primitives, string, enums, Unity built-in types such as Vector3 and Color, and UnityEngine.Object subclasses already implement GetHashCode and Equals correctly. You don’t need to override them.

For value-type keys, also implement IEquatable<T> to avoid boxing allocations during key comparisons. IEquatable<T> isn’t required, but it improves runtime performance.

If a custom GetHashCode or Equals implementation throws an exception while Unity loads a serialized dictionary, Unity skips the affected entries and logs one console warning.

Edit a dictionary in the Inspector

When you select a GameObject or an asset that contains a serialized dictionary, the Inspector renders the dictionary as a two-column list with the keys on the left and the values on the right.

The Inspector provides the following features:

• Add or remove an entry with the + and - buttons at the bottom of the list.
• Change the width of columns. The width persists per property path and per Inspector window.
• Right-click the column header to change the layout. Refer to Customize the dictionary display.
• Right-click the column header and select Reset to Defaults to restore the default layout, column split, and sort direction.
• Toggle the sort direction by clicking the Key column header.
• Right-click the column header and select Show Serialized Order (Global) to display entries in their serialized order instead of sorted by key. This setting applies to every dictionary and persists for the current Editor session. It’s useful for debugging prefab overrides. Refer to Dictionaries in prefabs.

Dictionary fields don’t support multi-object editing. When you select more than one GameObject or asset, the Inspector displays a help box in place of the dictionary editor.

Sort order in the Inspector

The Inspector sorts entries by key for display only. Sorting doesn’t change the serialized order, which always reflects the order in which entries were added. Click the Key column header to toggle between ascending and descending order.

The Inspector reads each key directly from the serialized data and compares fields based on their property type. It doesn’t call the comparison interface IComparable<T> or its CompareTo method on the key type, so you don’t need to implement them for sorting in the Inspector.

The following table describes the sort behavior for each supported key type:

Key type	Sort behavior
int, long, short, byte, and other integer types	Numeric order.
float, double	Numeric order. NaN values sort last.
string	Case-insensitive natural order: digit runs are compared as numbers, so item2 appears before item10.
bool	false before true.
Enum types	Sorted by enum value index, which matches the order in which you declared the enum members.
References to UnityEngine.Object subclasses	Sorted by internal entity identifier.
Structs and classes	Sorted field by field, in declaration order. Refer to Complex key sort order.

Complex key sort order

When a dictionary key is a struct or serializable class, the Inspector compares entries one field at a time, in the order the fields are declared in your script. It compares the first field of each key. If those values are equal, it moves to the second field, and so on. To change the sort priority, reorder the field declarations in your class.

Only fields visible in the Inspector contribute to the comparison. Fields marked [HideInInspector] are skipped. The comparison recurses into nested structs and classes up to eight levels deep. Beyond that, remaining nested fields are treated as equal and Unity logs a one-time console warning.

When sort order updates

The Inspector re-sorts the displayed entries in the following situations:

• When you add or remove an entry.
• When a key field changes, after you commit the edit (for example, by leaving the field or pressing Enter).
• When external code modifies the serialized property.

While you’re actively typing in a key field or dragging a slider, the Inspector defers the re-sort to avoid moving the row out from under you. Duplicate-key markers update in real time so you still see immediate feedback. When you complete the edit, the Inspector re-sorts and your current selection is preserved across the new order.

Customize the dictionary display

Apply the [DictionaryDisplay] attribute to a dictionary field to set the column layout, the column labels, and the initial column split:

using System.Collections.Generic;
using UnityEngine;

public class LootTable : MonoBehaviour
{
    [SerializeField]
    [DictionaryDisplay(keyLabel = "Item", valueLabel = "Drop chance", keyColumnFraction = 0.6f)]
    private Dictionary<string, float> drops = new Dictionary<string, float>();
}

[DictionaryDisplay] has the following parameters, all of which are optional:

• keyLabel and valueLabel set the labels for the key and value columns. If you leave one empty, Unity uses a default label (Key or Value).
• keyColumnFraction sets the fraction of the available width assigned to the key column. Valid values are between 0.01 and 0.99. The default value is 0.5.
• layout sets the column layout. For more information, refer to Choose a layout.

The parameters set only the initial presentation. If you change the presentation in the Inspector (for example, by dragging the column divider or changing the layout from the header context menu), Unity saves your choice and ignores the initial parameters on later draws. To return to the values set by the attribute, right-click the column header and select Reset to Defaults.

Choose a layout

To determine how the Inspector arranges keys and values, set the layout parameter to one of the following DictionaryLayout values:

Layout	Description
TwoColumns	Shows keys and values side by side in two resizable columns. This is the default value.
OneColumnWithValueVisible	Stacks each value under its key in a single column, with every value shown inline.
OneColumnWithValueFoldout	Stacks each value under its key in a single column, with every value behind a collapsible foldout.

You can also change the layout from the column header’s context menu, which overrides the layout set by the attribute.

Customize a dictionary by type

The [DictionaryDisplay] attribute is a field attribute, so it configures only the single field you attach it to. Apply [DictionaryDisplayForType] as an assembly-level attribute instead when you want to:

• Configure a dictionary that has no field to decorate, such as the inner dictionary of a Dictionary<int, Dictionary<string, SkillLevel>>, which is a value rather than a field.
• Apply one consistent presentation to every field of the same dictionary type from a single declaration, instead of repeating [DictionaryDisplay] on each field.

Name the exact dictionary type with typeof. The attribute applies to every dictionary of that exact type, wherever it appears:

using System.Collections.Generic;
using UnityEngine;

// One declaration configures every Dictionary<string, SkillLevel> in the assembly: the nested
// dictionary in Character and the field in AbilityBook, without repeating [DictionaryDisplay].
// This assembly defines SkillLevel, which the attribute requires.
[assembly: DictionaryDisplayForType(typeof(Dictionary<string, SkillLevel>),
    layout = DictionaryLayout.OneColumnWithValueVisible,
    keyLabel = "Skill", valueLabel = "Level")]

[System.Serializable]
public struct SkillLevel
{
    public int rank;
    public float bonus;
}

public class Character : MonoBehaviour
{
    // Nested inner dictionary: a value, so it has no field to decorate.
    [SerializeField]
    private Dictionary<int, Dictionary<string, SkillLevel>> skillsPerTier = new();
}

public class AbilityBook : MonoBehaviour
{
    // A direct field of the same type, styled by the same declaration.
    [SerializeField]
    private Dictionary<string, SkillLevel> learnedSkills = new();
}

[DictionaryDisplayForType] accepts the same parameters as [DictionaryDisplay] and applies all of them. The type you pass to typeof has two requirements:

• It must be a fully specified Dictionary<TKey, TValue>, such as Dictionary<string, SkillLevel>. Unity ignores a target that isn’t a fully specified dictionary type. The analyzer reports UAC1021.
• It must use a type defined in the same assembly as the attribute: its key type, its value type, or a type nested inside either. For example, an assembly that defines SkillLevel can target Dictionary<string, SkillLevel>, Dictionary<int, SkillLevel[]>, or Dictionary<int, List<SkillLevel>>. This prevents a rule in one assembly from changing a dictionary built only from types it doesn’t define, such as Dictionary<int, int>. If the target uses no type from the attribute’s assembly, Unity ignores the rule and logs a warning in the console. The analyzer reports UAC1022.

When a dictionary is nested as the value of another dictionary, the Inspector uses Dictionary as the label for the inner dictionary’s foldout, because a dictionary value has no field name.

Resolution order

When more than one source can set a dictionary’s presentation, Unity uses the first source that applies, from highest precedence to lowest:

1. The user’s own in-editor choices: the layout from the header context menu and the column width from dragging the divider. Unity persists these choices per property path until the user selects Reset to Defaults.
2. A field-level [DictionaryDisplay] on the dictionary field sets the layout, labels, and width.
3. An assembly-level [DictionaryDisplayForType] on the exact Dictionary<TKey, TValue> sets the layout, labels, and width.
4. The built-in defaults: TwoColumns layout, Key and Value labels, and a 0.5 key-column fraction.

Duplicate keys

A dictionary can contain only one value for each key at runtime, but the Inspector lets you create duplicate keys temporarily so you can resolve them incrementally. Unity marks each duplicate row with an icon and a tooltip, and preserves the duplicate entries in the asset until you correct or remove them. Duplicate entries are tracked per host object only in the Editor; the Player runtime always enforces unique keys.

When Unity loads a scene, prefab, or asset that contains a serialized dictionary with duplicate keys, or when you instantiate an object that contains such a dictionary, the Editor writes a warning in the console. Unity adds only the first occurrence of each duplicate key to the runtime dictionary.

If you need to read the duplicate indices from a custom Inspector or other tooling, use SerializedProperty.GetDictionaryDuplicateEntryIndices.

Null keys

A dictionary can’t contain a null key at runtime, but the Inspector keeps a row whose key is null so you can assign a valid key to it. A row has a null key when you add an entry with the + button and haven’t set the key yet, or when a UnityEngine.Object key is unassigned or refers to an object that no longer exists. Unity marks each null-key row with an icon and a tooltip, and preserves the row in the serialized data so you don’t lose it or its value.

When Unity loads a scene, prefab, or asset that contains a serialized dictionary with null-key rows, or when you instantiate an object that contains such a dictionary, the Editor writes a warning in the console and excludes those rows from the runtime dictionary. Unity keeps each null-key row as a separate placeholder rather than merging rows that share a null key, so no value is lost.

If a dictionary contains both duplicate keys and null keys, Unity reports them in a single console warning rather than one warning for each problem.

If you need to read the null-key indices from a custom Inspector or other tooling, use SerializedProperty.GetDictionaryIgnoredEntries and read its nullKeyEntryIndices array.

Dictionaries in prefabs

You can override individual entries of a serialized dictionary on a prefab instance. The Inspector indicates each overridden key or value the same way it indicates other property overrides, and you can apply or revert each overridden key or value independently.

Unity records dictionary overrides using the serialized position of the entry, the same way it records overrides on array and list fields.

Dictionaries add extra complexity for prefab overrides. The Inspector displays entries in sorted order rather than in the order they were added or stored, so the row position you see doesn’t correspond to the entry’s storage position. After you delete or add an entry on the prefab asset, review the instance overrides to confirm they still apply to the entries you intended.

To make overrides easier to reason about, right-click the column header and select Show Serialized Order (Global). The Inspector then displays entries in their serialized order, so each row’s position matches the storage index that Unity records the override against.

For the logic behind this behavior and an example, refer to Overrides on arrays, lists, and dictionaries.

Limitations

• Multi-object editing isn’t supported. The Inspector shows a help box when more than one target is selected.
• Since Unity records dictionary overrides using the serialized array index, editing a dictionary on a prefab asset can leave existing instance overrides applied to a different entry. For more information, refer to Overrides on arrays, lists, and dictionaries.
• The Inspector sort order doesn’t change the serialized order, which always reflects insertion order.

Additional resources

• Serialization rules
• Serialization rules analyzer
• Custom serialization
• DictionaryDisplayAttribute
• DictionaryDisplayForTypeAttribute
• DictionaryLayout
• SerializedProperty.GetDictionaryDuplicateEntryIndices
• SerializedProperty.GetDictionaryIgnoredEntries
• DictionaryIgnoredEntries