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 and classes that contain a [SerializeReference] field — directly or anywhere in their field graph or inheritance chain — can be used as either a key or a value in a serialized dictionary.

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.

Custom key comparers

To control how a serialized dictionary compares and hashes its keys, pass an implementation of the IEqualityComparer<TKey> interface to the dictionary constructor in the field declaration:

using System;
using System.Collections.Generic;
using UnityEngine;

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

Unity doesn’t write the comparer to a scene, a prefab, or an asset. A comparer still applies after a load only if you pass it to the constructor in the field declaration. This is because Unity reuses the dictionary that the field already contains instead of creating a new one: it calls the Clear method on that dictionary and then adds the entries it reads. The Clear method doesn’t reset the comparer.

Which dictionary the field contains depends on the operation:

• An operation that creates the object that contains the dictionary runs the field declaration first, so the dictionary uses the comparer you declared. This includes the following operations: domain reloads, scene loads, prefab loads, asset loads, and calls to the Object.Instantiate method.
• An operation that deserializes into an object that already exists reuses whichever dictionary the field contains at that moment, and doesn’t run the field declaration again. This includes the following operations: undo, redo, prefab revert, and calls to the SerializedObject.ApplyModifiedProperties method. The declared comparer still applies, unless a script replaced the dictionary or set the field to null after Unity loaded the object. If the field is null, Unity creates a new dictionary with the default comparer, and doesn’t apply the declared comparer again until it next creates the object.

Set the comparer in the field declaration

The serialized data doesn’t include the comparer, so Unity can’t restore a comparer that exists only on a dictionary that a script assigns at runtime. For more information, refer to Comparers that Unity can’t preserve.

For example, the following script loses its comparer the next time Unity creates the object, such as after a domain reload. The SetValues method replaces the field with a dictionary that has a comparer, but the field declaration doesn’t set one, so the reloaded asset compares keys case-sensitively:

using System;
using System.Collections.Generic;
using UnityEngine;

public class ItemLookup : ScriptableObject
{
    [SerializeField]
    private Dictionary<string, int> values = new Dictionary<string, int>();

    public Dictionary<string, int> Values => values;

    // A caller supplies the comparer, for example:
    // lookup.SetValues(new Dictionary<string, int>(StringComparer.OrdinalIgnoreCase));
    public void SetValues(Dictionary<string, int> newValues)
    {
        values = newValues;
    }
}

To keep the comparer, pass it to the constructor in the field declaration:

[SerializeField]
private Dictionary<string, int> values = new Dictionary<string, int>(StringComparer.OrdinalIgnoreCase);

With this declaration, the dictionary uses the declared comparer again the next time Unity creates the object, even if a script replaced the dictionary at runtime.

Until Unity creates the object again, the field contains the dictionary assigned at runtime, and an in-place operation such as undo uses that dictionary’s comparer instead of the declared one. To get the same behavior in both cases, give any dictionary that you assign at runtime the same comparer as the field declaration.

Don’t replace the dictionary in Awake or OnEnable

Don’t assign a new dictionary to the field in a MonoBehaviour method that Unity calls after it deserializes the object, such as Awake, OnEnable, or Start. A new dictionary discards the entries that Unity loaded. To set a comparer, pass it to the constructor in the field declaration, which runs before deserialization.

Duplicate keys caused by a comparer

A comparer can make two different serialized keys equal. For example, the keys Alpha and alpha are different strings in the serialized data, but the StringComparer.OrdinalIgnoreCase comparer treats them as the same key.

Unity reports this as a duplicate key: it adds the first entry to the runtime dictionary, excludes the later entries, and marks each excluded row in the Inspector so you can correct or remove it. This is the same behavior as any other duplicate key. For more information, refer to Duplicate keys.

Comparers that Unity can’t preserve

Unity can’t restore a comparer that a script set on the dictionary in the following cases:

• A comparer selected at runtime. A field declaration is fixed at compile time, so it can’t specify a comparer that a script chooses while it runs, for example from a loaded value, a project setting, or a method argument. Unity can’t read the comparer back from the serialized data, so nothing restores the choice.
• A dictionary inside a struct. C# doesn’t allow field initializers on struct fields, so a struct declaration can’t create the dictionary or set a comparer on it. Unity reads the fields of a serialized struct in place, inside the object that contains the struct.
• A dictionary used as a value. In a Dictionary<string, Dictionary<string, int>> field, Unity creates each inner dictionary as it reads the entries, so an inner dictionary has no field declaration that could set a comparer. The outer dictionary is a field, so it keeps the comparer that you set on it.

In each of these cases, the dictionary uses the comparer from the field declaration, or, if the field declaration doesn’t set one, a comparer that behaves the same as the one that the EqualityComparer<TKey>.Default property returns.

The limitation on a dictionary used as a value applies only when the value is itself a dictionary. If the value is a [Serializable] class that has a dictionary field, that dictionary keeps the comparer from its field declaration, as long as the class has a parameterless constructor. Unity creates the class with that constructor, so the field declarations of the class run. If the class declares only constructors that take parameters, Unity creates the class without running a constructor, the field declarations don’t run, and the dictionary uses the default comparer.

If you need a custom comparer in one of these cases, restructure the data so that the dictionary is a field whose declaration can create it. For example, move the dictionary out of the struct and into a [Serializable] class that has a parameterless constructor, then set the comparer in that class’s dictionary field declaration.

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 Layout 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 Layout.

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 Layout.
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.GetDictionaryIgnoredEntries and read its duplicateEntryIndices array.

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.
• Unity doesn’t serialize a dictionary’s key comparer. A comparer applies after a reload only if you pass it to the constructor in the dictionary field declaration. Refer to Custom key comparers.

Additional resources

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