Unity Features 101: Assembly Definitions

When you create your project in Unity, the Unity engine groups all your scripts into one assembly or in other words a “group”. This is assembly is predefined by Unity as Assembly-CSharp.dll. This assembly allows all your scripts to know of each other and communicate but also they all compile together. Let’s see how this is not a very good thing and we can solve it.

Single Assembly Draw-Backs

As you now know, as a default Unity groups all your scripts into one default Assembly. So what does this mean?

1. All your scripts have direct access to each other and can communicate together. This can be good for small projects, but for big projects, things get pretty complicated and you might fall into a spaghetti code.
2. Each time you change just one line or add a single space in one of your scripts, then whenever you save this script, Unity has to compile every single script in this Assembly which lead to higher and higher compilation time as your project gets bigger and bigger. For small projects that is completely fine, but bigger projects take a big hit on their compilation time.

Assembly Definition Benefits

To solve the above issues, we can create our own Assembly Definitions and references. In other words, we can group our scripts into different groups. How does this help us?

1. Your code base will be way more organized and your are forced into writing a better and cleaner code.
2. They way Assembly Definitions work, is that if you change a script in one Assembly, then Unity only has to recompile the scripts that are ONLY inside this Assembly and doesn’t have to recompile ALL the scripts in your project. Which means, compilation times will be cut drastically.
3. Assemblies also gives you the ability to compile a script only on one platform but not on another. For example, say you have a group of scripts put in an Assembly but they ONLY work on Android. You can set this Assembly to only compile on an Android platform and not on the others.

Create Your Own Assemblies

Before going into the “limitations” of Assembly Definitions that force into writing a cleaner code, let’s see how we create them.

A. To create an Assembly, first you have to group the scripts you want to assemble together in a separate folder.

Create an Assembly Definition

Then you right click in the folder, Create > Assembly Definition and name it. Unity will automatically put all these scripts that are in this folder under this Assembly, call it TestAssembly.

Now if you inspect any script in this group, you will see that it is now in the Assembly you have created.

Assembly Check

Now each time you create a script in this folder, it will be automatically complied in this new Assembly you have created.

B. Let’s say you want to create a new script in a different folder but you want it to be included in the TestAssembly. As it is, it will not be able to communicate in the scripts of the TestAssembly. You cannot simply duplicate the TestAssembly and put it in your new folder. But you can create an Assembly Definition Reference. Right Click in your new folder then Create > Assembly Definition Reference. Click on this new reference, and drag your TestAssembly into the reference. Now the scripts in your new folder will be grouped in your TestAssembly.

As you can see, I have created an Assembly Definition Reference and dragged the TestAssembly into it. Now all scripts in the new folder are compiled together with the TestAssembly.

C. Say you have two different Assemblies A and B, and you want to allow B to know and communicate with A.

Simply click on Assembly B, and under Assembly Definition References, add a new reference and drag Assembly A into this reference. Now, Assembly B can communicate with Assembly A BUT Assembly CANNOT communicate with B.

Assembly Definitions Limitations

Actually the way I see it, there is only one limitation when using Assembly Definitions and that is two Assemblies cannot reference each other. In other words, you are not allowed to have a circular dependency when it comes to Assemblies.

So Assembly A can reference Assembly B, but once you apply this reference, now Assembly B cannot reference Assembly A. This happens because Unity will not be able to know which Assembly to compile first so it doesn’t allow this. Think of it as a hierarchy; the Assembly that is above can reference the Assembly below it, and the one below it cannot reference the one above it.

#Unity Assembly Hierarchy

This is by no means a bad thing because this limitation forces you into thinking before creating your scripts and writing your code. This will allow you to create a better and cleaner code because now you have to organize your scripts in a way to allow communication between different scripts and assemblies.

So if done right, Assembly Definitions is a Unity feature that I believe must be known by every Unity developer that allows for a cleaner code and faster compilation time.