Managing Meta Files in Unity

December 8, 2015

If you’re working on a team that uses Unity then you’ve probably run into issues with meta files and source control. Missing meta files, conflicting meta files, and more. It’s a huge, confusing pain in the ass.

The good news is the errors are neither magic nor random. They all happen for a reason. Once understood they can be guarded against to prevent them from happening again.

Globally Unique Identifier

What is a Unity meta file? Meta files store data about an asset that can’t be stored inside the asset. For example texture import settings can’t be stored in a .png so they’re stored in a meta file.

When using source control we want to enable visible meta files. Once enabled every asset you create will have a matching meta file generated by Unity. For example:

    Enemy.prefab
    Enemy.prefab.meta

    CastSpell.cs
    CastSpell.cs.meta

    Fireball.png
    Fireball.png.meta

Meta files are simple text files that are human readable. Here’s an example:

    fileFormatVersion: 2
    guid: de9a32f15f2628044842629a83d3d974
    timeCreated: 1442592418
    licenseType: Free
    MonoImporter:
    serializedVersion: 2
    defaultReferences: []
    executionOrder: 0
    icon: {instanceID: 0}
    userData: 
    assetBundleName: 
    assetBundleVariant:

For this post there’s only one line we care about.

    guid: de9a32f15f2628044842629a83d3d974

A guid is a globally unique identifier. Every asset has a meta file and every meta file has a unique guid. The guid is randomly generated when the meta file is created. Most pain and suffering related to meta files has to do with this guid.

References

Unity objects reference each other by guid. The Enemy prefab has a CastSpell component identified by guid. The CastSpell component has a texture referenced by guid.

Raise your hand if you’ve encountered the dreaded missing Behavior error.

Unity Error

It’s particularly frustrating because there are no hints about what behavior is missing. Thanks Unity.

The issue is that Unity could not find an asset with guid de9a32f15f2628044842629a83d3d974. Unity only stores the guid. If the guid can’t be found then you’re screwed.

Catastrophic Failure

There is one particular case that is catastrophic. It causes the majority of meta file related anguish.

Changing an existing guid is catastrophic.

Changing a guid breaks all references and generates behavior missing errors. You should never ever change a guid.

The good news is you never change guids intentionally. The bad news is you can indirectly cause it to happen.

Duplication

Duplicating a guid is also catastrophic. If Unity encounters a duplicate guid then it will replace the one of the two with a newly generated value. That means Unity changed a guid. Which is catastrophic.

Error Operations

Given that changing a guid is catastrophic and by extension duplicating guids is catastrophic there are a handful of user operations which can cause either catastrophe to happen.

1. Submitting new asset without meta file

Easily the most common mistake. Especially when using source control. You created a script or texture but forgot to the submit the matching meta file.

This mistake cascades into catastrophe. If you forget to submit a meta file and I sync then I will generate a new meta file. However my file will have a different guid than your file. If you also checked in objects with references to your guid then on my machine those references will become missing behavior errors.

When this case happens the person who originally created the file must submit their meta file. If I submit my meta file then when you sync you’ll get a new meta file with a new guid which is changing a guid which is catastrophic.

2. Unpaired asset/meta file

Assets and meta files should always be created and deleted as a pair. When using source control you also need to submit add operations or delete operations as a pair.

Here are three different mistakes which can be made. These mistakes are uncommon so I’m lumping them together.

These are all straight forward and easy to fix. They are more disruptive and confusing than catastrophic.

3. Manually copied asset + meta file to new location

If you copy an asset and it’s meta file in Windows Explorer/OS X Finder then you have a duplicated guid. Which is catastrophic.

When moving assets always do it through the Unity editor. Unity correctly handles moving assets and their meta files.

4. Moved asset but left old file in source control

When you move an asset through the editor there are two source control operations. You are deleting old files and adding new files. You must submit both operation sets.

If you submit only the add operation but not the delete operation then your machine will be fine. When I sync my machine I will have both the old files and the new files which means a duplicate guid. Which is catastrophic.

5. Empty folders generating meta files

Unity generates meta files for folders. Perforce ignores folders entirely. If all the files are deleted in a folder and you sync Perforce it will delete the files but leave the empty folder. If the folder meta file was deleted then Unity will see the empty folder and generate a new meta file. Urgh!

It’s somewhat harmless. However if you reconcile with Perforce it’s super important to have a “clean” reconcile. If there is cruft then you’re more likely to submit an error that does matter.

I use a tool to remove empty directories. I run this tool periodically after syncing latest.

Words

We’ve established that there are certain catastrophic failures and they can happen in a variety of ways. The good news is that knowing is half the battle! The other half is writing tools to detect errors before they are submitted to source control.

Managing Folder Meta Files

Folder meta files are worthless. They literally do nothing for us. Our solution is to never submit them to source control. We use Perforce and achieve this through the .p4ignore file.

# Ignore: name DOT meta
*.meta

# Include: name DOT extension DOT meta
!*.*.meta

There are some caveats with this approach. One, it fails to ignore folders with a dot in their name. Two, it incorrectly ignores valid files if they lack an extension. Such as README on Unix.

We handle these infrequent cases with special casing in sub-directory .p4ignore files.

# Ignore
Steamworks.NET.meta
Steamworks.NET\*.meta

# Include
!Steamworks.NET\*.*.meta

This approach may not work in all cases. It may not be appropriate for your project. It may not matter if you use git/svn. For us it has worked splendidly well.

(Update: Unity 5.3 was intended to have updates to package importing but it got delayed. Details here. It may make sense to keep folder meta files under our External directory but exclude them for our internal code.)

Source Control Verification

Wouldn’t it be great if you could detect and block source control operations that would result in a catastrophic error? Good news, you can!

We use Perforce Triggers which do exactly that. My friend and co-worker Jørgen Tjernø wrote ours. He was even kind enough to share them on GitHub with excellent documentation. Thanks Jørgen!

Here are the three things our triggers check for:

If a changelist fails these checks then it is not submitted and an error message is displayed.

Perforce Error

Here are two things they do NOT check (but we wished they did):

The first one is tricky. Our naive implementation was too slow. The second is a case we missed the first time around and hasn’t been added yet.

Again, these Perforce scripts and detailed installation instructions are available on GitHub courtesy Jørgen Tjernø. They’re super duper great and I can’t recommend them enough. Stopping errors before they happen is the best.

Git/Mercurial Scripts

We use Perforce so we have only written Perforce scripts. If any enterprising readers would like to write similar scripts for Git or Mercurial I will gladly update this section with links.

Source Control Integration

Some of these issues can also be caught with source control editor integration. Unfortunately Unity Asset Server is now an unsupported legacy product. And P4Connect doesn’t actually work. Not reliably at least. We stick with the tried and true reconcile method through P4V.

Advanced Maneuvers

When it comes to rules there are always exceptions. Some users want to copy a meta file and let Unity generate a new guid. Some users want to use Explorer for moving and renaming assets.

If you know what you’re doing it’s fine. Go for it. Our team has led a happier more productive life by establishing some rules. Do what’s best for your team.

Closing Thoughts

Meta files can be frustrating. Especially when using Unity for the first time. I can’t promise this post covers every error. But it does cover everything I’ve encountered so far.

My hope is that this post can serve as a guide to programmers, artists, and designers. Understanding and tooling combined can go a long ways towards a happy, frustration-free game development experience.