Understanding .meta Files and GUIDs

In this article we explain how Unity uses .meta files and GUIDs to keep track of the Assets in your project. Along the way we’ll learn how GUIDs are critical to the tracking of references between objects in Unity.

Assets are tracked by GUID, not by name

The first thing to understand, and this might be a bit surprising at first, is that Unity Editor doesn’t care about the name of the Assets in your project.

The reason it doesn’t care is because it assigns every Asset a Globally Unique Identifier (GUID) and uses that GUID to track the Asset within your project.

Diagram showing an Asset GUID in Unity

If you think about it, that makes a good deal of sense. By using GUIDs, Unity can’t become confused when a developer accidentally gives two Assets the same name.

It also allows Unity to keep track of Assets when you move or rename them. If you have ever tried moving an Asset to a new folder or renaming it in the Editor, you’ll find that all the references to Asset remain intact.

Reorganizing your texture assets into sub-directories? Renaming an Ogre to Troll? The Unity Editor’s got your back, keeping any references intact within the project.

 Pro tip: By using the Unity Editor to make changes to Assets, you reduce the odds of them becoming broken. If you are using git for source control, our MetaBuddy plugin for Unity helps you automatically detect any breakages before you commit them.

References between objects are stored as GUIDs

When one object in our project references another, for instance a Material referencing a Texture, the referencer object holds a copy of the referenced object’s GUID.

In the case of a Material referencing a Texture, the Material would hold a copy of Texture’s GUID. The referencer uses the GUID to “point forwards” to the object being referenced. This is illustrated in the diagram below:

Diagram showing how Unity uses GUIDs to track references between Assets

Asset GUIDs are stored in .meta files

Ever wondered what those mysterious files ending with .meta are doing in your project’s Assets/ directory?

They contain two key items of information:

  • The GUID for the Asset
  • The Asset’s settings that you see the Editor’s Inspector pane. (eg. The compression mode for a Texture or the color of a Material)

Once we understand this is, it should be clear that meta files aren’t something created by our version control system or an irritating side effect that we can turn off.

 Key point: Meta files contain valuable information that isn’t stored elsewhere. Hence, they form an integral part of your project.

This means that they should be checked into your version control system along with the rest of your project.

Unity Assets live in pair of files

Unity creates and maintains a meta file for each Asset in your project. It associates the Asset’s content file with its meta file through its filename.

For instance an Asset with a content file Explosion.png would have a meta file named Explosion.png.meta stored alongside it.

Diagram showing how Unity meta files are linked to assets by filename

 Separated files → Project Breakages The two files (content and .meta) for an Asset need to stay together as a pair. If they ever become separated then something in your project is going to get broken.

Exactly how the breakage will manifest itself depends on the circumstances. We cover these kind of breakages and how to avoid them here

Altering an Asset’s GUID will break all references to that Asset

The downside to relying on GUIDs to identify Assets is that changing a GUID is a catastrophic event. When a GUID changes, all references to that Asset will become broken.

Diagram of a broken reference between Assets in Unity

In many cases, the Unity Editor either remains silent about broken references, or waits until you hit Play before bringing them to your attention.

If you have ever seen the “The referenced script on this Behaviour is missing!” message in Unity’s Console pane, you are seeing the effect of a broken reference to an Asset, a Script in this case.

The two files (content and .meta) for an Asset need to stay together as a pair. If they ever become separated then something in your project will get broken.

 Pro tip: While Unity is pretty vocal about broken references to Script Assets, it is less vocal about other Asset types.

In many cases, a broken reference will go unnoticed until someone notices that it looks wrong at runtime.

What next?

Hopefully this page helped you to get a fair understanding of how .meta files and GUIDs are used by the Unity Editor to track your Assets.

If you are looking for best practices to avoid common issues with meta files, head over to avoiding broken references

Check out the FAQ for answers to specific Asset and meta file questions. Alternatively, see the Meta File Deep Dive article if you are interested in learning more about what happens under the hood.