Working with Assembly Definitions

1. What is an Assembly Definition?

This tutorial has been verified using Unity 2019.4.10f1 LTS - https://learn.unity.com/tutorial/working-with-assembly-definitions-2019-3

In this tutorial, we’ll explore Assembly Definitions. An Assembly Definition groups code into an Assembly. An Assembly might be based on origin, purpose, and/or whatever criteria best suits your project. An Assembly Definition can also depend on the platform. By default, all code in a Unity project belongs to a single Assembly, called Assembly-CSharp.

Any change made to a script in an Assembly causes all code in the Assembly to be recompiled, and the Assembly rebuilt. This will slow down a Unity project in which every script is part of the main Assembly; that slowdown worsens as the script count grows. By separating code into Assemblies, you can greatly reduce the impact of code updates.

After an Assembly is rebuilt, any Assemblies that depend on it are also rebuilt, and the main Assembly depends on all defined Assemblies. It is for this reason that you want to assign all code to an Assembly if you assign any. Let’s say you have 10 scripts, but only three are assigned to custom Assemblies. When any custom Assembly is rebuilt, the main Assembly is also rebuilt, which means those seven scripts all need to be recompiled.

2. Creating (and assigning code to) an Assembly Definition

An Assembly Definition exists as an Asset inside a folder that also contains code belonging to that Assembly. Code in any subfolders that do not contain their own Assembly Definition also belong to the Assembly.

To create an Assembly Definition, first create a folder in your project to hold the Assembly and associated code. Inside the folder, in the Project view, right-click and select
Create > Assembly Definition.

All code in this folder, and any subfolder, is now part of this new Assembly, rather than the default main Assembly. If you later decide to branch off one of the subfolders into its own Assembly, you need only create a new Assembly Definition in that subfolder. All code in the subfolder, and any subfolder within it, will then belong to the newer Assembly.

3. Editing an Assembly Definition

To edit an Assembly Definition, either select it in the Project view and use the Inspector (Figure 01), or double-click to open it in your script editor.

Figure 01: Options for a New Assembly

4. Assembly Definition Options

General

Allow ‘unsafe’ Code: Checking this option includes members and methods that are marked unsafe.

Auto Referenced: Checking this option causes predefined Assemblies to automatically reference this Assembly Definition.

Override References: Checking this option allows you to specify the precompiled Assemblies you want this Assembly Definition to reference. Left unchecked, this Assembly Definition refers to all auto-referenced precompiled Assemblies.

No Engine References: When Checking this option, Unity does not add references to the UnityEditor or UnityEngine when it compiles the Assemblies.

Define Constraints: Including a Define Constraint will cause the Assembly to build only if the constraint returns true. Define symbols are set per platform in the Player settings. To add Scripting Define Symbols, select Project Settings from the Edit drop-down and select Player in the left column (Figure 02), and expand the Other Settings dropdown.

Figure 02: Scripting Define Symbols are defined in Player Settings, under Other Settings.

Assembly Definition References

Use GUIDs: This allows you to include Assemblies by their GUID, rather than their name, allowing you to rename them without having to change the reference. Select the + symbol to add an Assembly.

Platforms: Your Assembly Definition can be set to build only on certain platforms. Note that if you are editing the .asmdef file in your script editor rather than the Inspector, you cannot use both includePlatforms and excludePlatforms keywords in the same Assembly Definition.

Version Defines: You can specify which version of packages and modules to include.

Aside from the platform definitions, it’s unlikely that you’ll actually need to edit your Assembly Definition file.

5. Conclusion

Assembly Definitions are extremely useful for managing dependencies in your project and optimizing compile times.