Unity YAML Guide

How Unity YAML Works in Scenes and Prefabs

Unity YAML is readable enough to inspect, but it is not simple. The real meaning of a scene or prefab is spread across object headers, local references, cross-file references, and nested asset relationships. Once you understand that, many Git review and merge problems make a lot more sense.

In short

Inside one file

Unity uses Class ID, File ID, and local references to describe an object graph.

Across files

Unity adds GUID and type information through meta-file identity and cross-file references.

Why review is hard

Meaning is distributed across IDs, hierarchy, and relationships rather than plain text.

Unity YAML is readable, but understanding it requires following several identity and reference layers at once.

Why Unity uses YAML in the first place

Unity stores many native assets, including scenes and prefabs, as text-based YAML so they can work with version control and remain inspectable outside the Editor. That is a major upgrade over opaque binary data. Teams can diff files, track changes, and recover from some classes of corruption or merge conflicts.

But there is a catch. Unity does not use the full YAML specification. It uses a subset optimized for its serializer, and it also diverges from standard YAML behavior in some cases. So while the file is human-readable, it is not designed as a friendly day-to-day editing format.

How object identity is encoded

Each object definition starts with a header like --- !u!1 &7618609094792682308. That line carries two important signals.

• !u!{Class ID} tells Unity which object class the entry belongs to.
• &{File ID} identifies the serialized object instance inside that file.

This is the first place where many review problems begin. Developers tend to read YAML as lines of property changes, but Unity is really storing a graph of typed objects with IDs and relationships. Once scenes or prefabs get large, that distinction matters.

Local references and cross-file references

Inside a file, Unity links objects through fileID. A Transform can reference its GameObject, components can reference sibling objects, and scripts can point at other objects in the same prefab or scene.

Across files, Unity needs more than fileID, because a File ID is only unique inside one asset. That is where .meta files and GUIDs come in. To reference an object outside the file, Unity combines:

• the asset GUID from the target file’s meta file
• the target object’s fileID
• a type field that helps Unity decide how the file is loaded

This is why raw review gets harder so quickly. A small line edit can actually mean a changed asset dependency, a broken prefab reference, or a swapped object target somewhere else in the project.

What changes when nested prefabs enter the picture

Nested prefabs and prefab variants raise the complexity sharply. Unity does not simply inline every object from the nested source. Instead, it serializes a PrefabInstance, source-prefab references, and a set of modifications or overrides. It may also generate stripped placeholder objects that exist mostly to preserve reference structure.

That means a review is no longer just about local object changes. It is about understanding how one file encodes changes relative to another prefab, which overrides are intentional, and which placeholder objects exist only as structural glue.

Why this matters for Git review

Once Unity YAML starts expressing object graphs, cross-file references, nested prefab relationships, and overrides, line-based review becomes a weak interface. The file may still be readable in theory, but the reviewer has to reconstruct a lot of hidden meaning mentally.

That is the real problem. Unity YAML is not impossible to read. It is expensive to reason about correctly under time pressure.

What teams actually need instead of raw text review

• object-level context for each change
• visible hierarchy paths
• clear reference changes
• override-aware review for nested prefabs
• validation before merge or apply

This is where a semantic workflow is stronger than plain YAML inspection. If a tool can surface changed objects, hierarchy, references, and prefab relationships directly, review becomes faster and much less fragile.

That is the direction behind Unity YAML Semantic Graph: not replacing Unity’s serializer, but giving teams a better review layer on top of it.

FAQ

Is Unity YAML standard YAML?

No. Unity uses a subset of YAML and diverges from the full YAML specification in some edge cases.

What is the difference between File ID and GUID?

File ID identifies an object inside one asset file. GUID identifies the asset itself across the project through its meta file.

Why does raw Unity YAML feel harder than normal config files?

Because it encodes relationships, references, and prefab structure, not just standalone properties.

Next step

If this clarified the structure but you still care about review pain, continue with why prefab overrides are hard to review in raw YAML or jump to a hierarchy-aware review workflow on the tool page.