YAML serialization of prefabs

Unity represents prefabAn asset type that allows you to store a GameObject complete with components and properties. The prefab acts as a template from which you can create new object instances in the scene. More info
See in Glossary instances, nested prefabs, and prefab variants in serialized sceneA Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More info
See in Glossary (.unity) and prefab (.prefab) files using a small set of related YAML elements. This page describes those elements and how they fit together.

Understanding this format is useful when you resolve merge conflicts in prefab files manually, inspect files produced by an automated build, or work with Unity assets from scriptsA piece of code that allows you to create your own Components, trigger game events, modify Component properties over time and respond to user input in any way you like. More info
See in Glossary that run outside the Editor.

For general information about Unity serialization format, refer to Format of text serialized files and UnityYAML. For annotated YAML examples from prefab files, refer to Example of YAML prefab serialization.

Prefab serialization elements

Unity represents a reference to a prefab inside a scene or another prefab file using four related elements:

• A PrefabInstance YAML element that links to the source prefab asset and records a set of override changes.
• An m_Modification block inside the PrefabInstance element that records individual property modifications and the objects added or removed relative to the source prefab.
• Stripped placeholder objects that let other objects in the same file reference specific objects inside the prefab instance (such as a child Transform).
• A prefab asset handle in the source prefab asset. Its fileID is always 100100000, and PrefabInstance objects reference it through the m_SourcePrefab property.

For information on how these elements are arranged in prefab variant files, refer to Prefab variants.

PrefabInstance element

Unity represents a prefab instance as a YAML document with class ID 1001 and document type PrefabInstance:

--- !u!1001 &<fileID>
PrefabInstance:
  m_ObjectHideFlags: 0
  serializedVersion: 2
  m_Modification:
    ...
  m_SourcePrefab: {fileID: 100100000, guid: <prefab-guid>, type: 3}

The key properties are:

• m_Modification: a block of data that records everything that differs between this instance and the source prefab. For more information, refer to The m_Modification block.
• m_SourcePrefab: a cross-file reference to the source prefab asset. The fileID is always 100100000 (the prefab asset handle), so only the guid value varies between references. For more information, refer to The prefab asset handle.

For a complete example of a prefab instance in a scene, refer to Prefab instance in a scene.

The m_Modification block

The m_Modification block stores data that differs between the instance and the source prefab, including property overrides and any objects that are added or removed. It has the following fields:

Unity writes empty lists for any of these fields even when there are no entries. A clean prefab instance with no overrides still contains m_Modifications: [], m_RemovedComponents: [], and so on.

Note: m_Modification (singular) is the name of the block. m_Modifications (plural) is the name of the property-override array inside the block. The two names differ by one letter.

Property modifications

Each entry in the m_Modifications array has four fields:

A typical property override uses the value field:

- target: {fileID: 599465214307944399, guid: 95cf80858ee0c4940b72f62b17aefd41, type: 3}
  propertyPath: m_LocalPosition.x
  value: 39.341
  objectReference: {fileID: 0}

An object-reference override uses objectReference instead, with an empty value field:

- target: {fileID: 1773024279374141337, guid: 89d4c08db6b9096438cb6c7718d47f26, type: 3}
  propertyPath: m_Material
  value: 
  objectReference: {fileID: 2100000, guid: 31321ba15b8f8eb4c954353edc038b1d, type: 2}

For more information about the {fileID, guid, type} format in references, refer to Direct reference asset management.

Stripped placeholder objects

A scene file or a containing prefab file can reference specific objects inside a prefab instance. For example, if a prefab instance’s root is a child of a GameObject in the scene, the parent GameObject’s Transform component contains the prefab instance’s root in its m_Children array.

In these cases, Unity doesn’t serialize the referenced object directly into the scene or containing prefab file. Instead, it adds a stripped placeholder element to that file. The placeholder contains only the information needed to identify the source object:

--- !u!4 &<fileID> stripped
Transform:
  m_CorrespondingSourceObject: {fileID: <source-fileID>, guid: <source-guid>, type: 3}
  m_PrefabInstance: {fileID: <PrefabInstance-fileID>}
  m_PrefabAsset: {fileID: 0}

The stripped keyword on the document header indicates that the object is a placeholder. The fields are:

The prefab asset handle

When Unity imports a .prefab asset, it creates a special object called the prefab asset handle with fileID 100100000. The handle doesn’t appear as a YAML document in the source .prefab file on disk. It’s generated during import and is stored in the prefab’s serialized artifact in the Library folder.

The handle is the target of the m_SourcePrefab reference on a PrefabInstance:

  m_SourcePrefab: {fileID: 100100000, guid: 95cf80858ee0c4940b72f62b17aefd41, type: 3}

Because fileID 100100000 is constant for every prefab, only the guid changes between references to different prefabs. The type: 3 indicates that the reference resolves to the imported artifact in the Library folder rather than to a file in the Assets folder. For more information about type values, refer to Type field values.

Prefab variants

A prefab variant is a .prefab file that inherits from a base prefab.

On disk, Unity represents a prefab variant’s root as a PrefabInstance element (class ID 1001) rather than as a separately serialized GameObject element. Inside that PrefabInstance, the m_Modification.m_TransformParent field has the value {fileID: 0}, because the instance has no parent inside the file. This is how Unity identifies a prefab as a variant.

The m_SourcePrefab field references the base prefab that the variant inherits from. The m_Modification block records the data unique to the variant, such as overridden property values, components, and added or removed objects, using the same format as any other prefab instance.

For an annotated example of a variant file, refer to Prefab variant.

Additional resources

• Example of YAML prefab serialization
• Format of text serialized files
• An example of a YAML scene file
• Direct reference asset management
• Nest prefab instances in other prefabs
• Create variations of prefabs
• Smart merge