Assembly Definitions in Unity

Markus X. Hofer
Jan 10 · 3 min read

Unity compiles our scripts into managed assemblies and by default it splits all our stuff into these assemblies:

  • Standard Assets and Plugins
  • Editor for Standard Assets and Plugins
  • Assets
  • Editor

So it has become good practice to put pieces that don’t change very often and aren’t referenced by any game code into the plugins folder to keep them from recompiling whenever the main code changes.

But now we have finally gained more control over this process and we can set up our own system by putting assembly definition files into our folders! So now — whenever files change — Unity will know only to recompile those assemblies that these files belong to (plus assemblies that have dependencies to those assemblies). What a great way to keeps compile times down, especially in large projects!

But of course there is a downside: We now need to carefully manage all the dependencies between our assemblies. Oh well.

How to

The way it works is we create an Assembly Definition file and put it in a folder. Then Unity will putt all the contents of this folder and all subfolders into an assembly.
If we put Assembly Definition files into subfolders they become their own assemblies.

Once we have an Assembly Definition, we can set it up to your liking.
We can add Define Constraints (meaning this assembly will only be available if the given keyword is in the Scripting Define Symbols).
We can set up Assembly Definition References to hook our assembly up to other assemblies that contain stuff that it needs to know about.
And we can choose which platforms an assembly supports. (Usually our runtime stuff will have Any Platform checked)

A simple assembly for all platforms

All our custom Inspectors and Editors need to be in a separate assembly that only supports the Editor platform and references the runtime assembly that contains everything that they’re dependent on.

Notice how the Any Platform toggle turns Exclude Platforms into Include Platforms! So one toggle secretly inverts the function of all the other toggles. That’s some “adventurous” UX design right there, Unity!

Editor assembly referencing the matching runtime assembly

By now you probably guessed it: More bad news. We can no longer simply put an Editor folder into every other folder, because that would mean we’d have to create a separate assembly definition for every single one of them. Ugh.
We could, however, structure our entire project differently and split it at the root level into Runtime and Editor and then keep an identical folder structure for both on the inside. Not as nice, but then we’d only need 2 assembly definition files instead of 10.000. The jury is still out on how to deal with this inconvenience…

Oh, you’re asking what the toggles for Auto Referenced and Override References do? Well, your guess is as good as mine. We will have to wait until someone from Unity descends down from the heavens to enlighten us by updating the ****** docs.

Markus X. Hofer

Written by

XR specialist, exploring the multitude of potential futures one prototype at a time.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade