Assembly Definitions in Unity
date
Jan 11, 2019
type
KnowledgeBase
year
slug
assembly-definitions
status
Published
tags
Unity
Assembly Definitions
summary
How to create your own assembly definition files so not all of your code has to recompile at every change.
An assembly is a C# code library that contains the compiled classes and structs that are defined by your scripts and which also define references to other assemblies.
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 keep compile time 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 put 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 our 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 bold and 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 f***** docs.
Originally published on my old blog on Medium here
