Assembly Definitions

You can use Assembly Definitions to organize the scripts in your Project into assemblies. When you create an Assembly Definition Asset in a folder, Unity compiles a separate managed assembly from all the scripts in that folder. ScriptsA piece of code that allows you to create your own Components, trigger game events, modify Component properties over time and respond to user input in any way you like. More info
See in Glossary in subfolders are included unless the subfolder has its own Assembly Definition. These managed assemblies act as a single library within your Unity Project.

An Assembly Definition Asset is a text file, with a file extension of .asmdef, that contains a JSON string that defines the Assembly Definition properties. Select the asset file to set these properties in a Unity InspectorA Unity window that displays information about the currently selected GameObject, Asset or Project Settings, alowing you to inspect and edit the values. More info
See in Glossary window. You can also use an external editor to edit the JSON directly. See Assembly Definition File format for information about the JSON syntax.

Assembly Definition benefits

When you separate your code into assemblies that have well-defined dependencies, Unity reduces their compilation time by only rebuilding the dependent assemblies when you make a change to a script. Assembly Definitions also help you manage dependencies in Projects that contain platform and Unity-version-specific code.

Without Assembly Definitions, Unity compiles any C# scripts in your Project into one of the predefined, managed assemblies. Unity must then recompile every script in the entire Project when you change any script. This means that the length of time between making a code change and seeing that change in action grows longer as you add more scripts to the Project.

Note: Although it’s not required, whenever you use Assembly Definitions in a Project, you should do so for all of the code in your Project. Otherwise, when you change scripts in one of the predefined assemblies, Unity has to still recompile all the code in your Project, because the predefined assemblies automatically depend upon any assemblies you create using an Assembly Definition.

The following figure illustrates a Project split into several assemblies:

By default, Unity compiles almost all Project scripts into the Assembly-CSharp.dll managed assembly. The example shows a Project that has been divided up into five separate assemblies instead. The Main.dll assembly depends on Stuff.dll and ThirdParty.dll. Stuff.dll depends on Library.dll, and so on. As a result, Unity doesn’t need to recompile any of the other assemblies because of a change to code in Main.dll. And since Main.dll contains fewer scripts, it compiles faster than Assembly-CSharp.dll. Similarly, if the code in Stuff.dll changes, Unity only needs to recompile Main.dll and Stuff.dll, not ThirdParty.dll or Library.dll.

Note: To find out where Unity compiles a particular C# file, select the script file in the Project window and look at the Assembly Information listing in the Inspector:

Assembly Definition Reference Assets

You can use Assembly Definition Reference Assets to add additional folders to an existing Assembly Definition asset.

Using Assembly Definitions

Add Assembly Definition Assets to folders in a Unity Project to define an assembly. After compilation, the assembly contains all the scripts in the folder and its subfolders (unless the subfolders have their own Assembly Definitions). Set the name of the assembly in the Inspector.

An Assembly Definition is a type of Unity Asset. You can select an existing Assembly Definition in the Project window to view or change its properties. See File Format for information about the Assembly Definition Asset file format.

To create an Assembly Definition Asset:

1. In the Project window, select the folder that you want to place the Assembly Definition
2. Go to AssetsAny media or data that can be used in your game or Project. An Asset may come from a file created outside of Unity, such as a 3D model, an audio file or an image. You can also create some asset types in Unity, such as an Animator Controller, an Audio Mixer or a Render Texture. More info
   See in Glossary > Create > Assembly Definition to create a new Assembly Definition
3. Select the new Assembly Definition you created
4. Set its properties in the Inspector window

To create an Assembly Definition Reference Asset:

1. In the Project window, select the folder that you want to add to an existing Assembly Definition Asset to
2. Go to Assets > Create > Assembly Definition Reference to create the Assembly Definition Reference Asset
3. Select the new Assembly Definition Reference you created
4. Set the Assembly Defintiion property so that it references the Assembly Definition asset that you want to add the additional folder to

You can only create one Assembly Definition or Assembly Definition Reference per folder.

If you create an Assembly Definition or Assembly Definition Reference in a subfolder of a folder that already has an Assembly Definition or Assembly Definition Reference, then Unity compiles any scripts in the subfolder and its children into the assembly defined in the subfolder, not the assembly defined in the parent folder.

Use GUID

The Use GUID option controls how Unity serializes the reference to the Assembly Definition Assets. When you enable Use GUID, Unity saves the reference as the Asset’s GUID, instead of the Assembly Definition name. It’s good practice to use the GUID instead of the name, because it means you can make changes to the name of an Assembly Definition Asset without having to update other Assembly Definition or Assembly Definition Reference files that reference it.

Version Defines

Use Version Defines to handle dependencies between different Resources and Packages in your current Project. This is useful if you want to share your Project through a Package Manager package or an Asset Store package.

To set a version, select the plus sign (+). You can add as many Version Defines to an Assembly Definition as you want. To delete a define, select it in the list, and click the minus sign (-).

When you add a Version Define, the following properties appear:

Property	Description
Resource	Select the Package or Module you want to set a define for. The list contains all active Packages and Modules in the Project.
Define	Set the name for the define. This define is only set if the Expression returns true.
Expression	The semantic version range of your chosen module or package. You must use mathematical interval notation. Wildcards are not supported. This uses the same version range as Microsoft’s .NET package manager, NuGet.
Expression outcome	Shows the mathematical equation that your Expression represents.

Backwards compatibility and implicit dependencies

To maintain compatibility with the existing Predefined Compilation System in Unity, the predefined assemblies reference every assembly you create with an Assembly Definition Asset. This is similar to how the predefined assemblies reference all the precompiled assemblies (such as plug-ins or .dlls) in the Project that are compatible with the active build target.

The following diagram illustrates the default dependencies between predefined assemblies, assemblies created with Assembly Definition Assets, and precompiled assemblies.

The numbers in the diagram indicate the references between the assemblies, which you can control as follows:

1. By default, assemblies you create with Assembly Definition Assets are referenced by the predefined assemblies. You can turn this off by disabling the Auto Referenced option in the Inspector for an Assembly Definition Asset. See Assembly Definition properties.
2. The predefined assemblies and assemblies created with Assembly Definition Assets both automatically reference Precompiled assemblies (plug-ins). To turn this default behavior off, disable the Auto Referenced property in the Plugin Inspector. For more information, see Plugin Inspector.
3. When you turn off Auto Referenced for a plug-inA set of code created outside of Unity that creates functionality in Unity. There are two kinds of plug-ins you can use in Unity: Managed plug-ins (managed .NET assemblies created with tools like Visual Studio) and Native plug-ins (platform-specific native code libraries). More info
   See in Glossary, you can explicitly reference it in the Inspector for an Assembly Definition Asset. Enable the Asset’s Override References option and add a reference to the plug-in. See Assembly Definition properties.

Note: If you turn off the Auto Referenced option for precompiled assemblies or assemblies Assembly Definition Assets creates, then classes in the precompiled assemblies can no longer reference or use the classes in these assemblies. You cannot declare explicit references for the precompiled assemblies.

Special folders

Unity treats scripts in folders with certain, special names differently than scripts in other folders. However, one of these folders loses its special treatment when you create an Assembly Definition Asset inside it or in a folder above it. You might notice this change iwhen you use Editor folders, which might be scattered throughout your Project (depending on how you organize your code and on the Asset packages you use).

Unity normally compiles any scripts in folders named Editor into the predefined Assembly-CSharp-Editor assembly no matter where those scripts are located. However, if you create an Assembly Definition Asset in a folder that has an Editor folder underneath it, Unity no longer puts those Editor scripts into the predefined Editor assembly. Instead, they go into the new assembly created by your Assembly Definition — where they might not belong. To manage Editor folders, you can do the following:

• Add an Assembly Definition Asset to each affected Editor folder and set the Platform property of that assembly so it is only used for the Editor Platform.
• Move all editor specific code to a central location not covered by an Assembly Definition.

Test assemblies

Test assemblies contain code that tests other code in your Project. As such, they don’t need to be included in release builds of your Project and other, non-test assemblies should not depend on them. If you want to use Test assemblies in Unity, see the Test Framework package documentation on How to create a new test assembly.

API

Use the CompilationPipeline class, in the UnityEditor.Compilation namespace, to retrieve information about all assemblies built by Unity for a project, including those created based on Assembly Definition Assets.

As an example, the following script uses the CompilationPipeline to list all the current Player assemblies in a project:

using UnityEditor;
using UnityEditor.Compilation;

public static class AssemblyLister
{

    [MenuItem("Tools/List Player Assemblies in Console")]
    public static void PrintAssemblyNames()

    {
        UnityEngine.Debug.Log("== Player Assemblies ==");
        Assembly[] playerAssemblies = 
            CompilationPipeline.GetAssemblies(AssembliesType.Player);

        foreach (var assembly in playerAssemblies)
        {
            UnityEngine.Debug.Log(assembly.name);
        }
    }
}

Assembly Definition File Format

Assembly Definition and Assembly Definition Reference Assets are JSON files. You can edit the Assets inside the Unity Editor or modify the JSON content with an external tool.

An Assembly Definition is a JSON object with the following fields:

Field	Type
name	string
references (optional)	string array
includePlatforms (optional)	string array
excludePlatforms (optional)	string array
allowUnsafeCode(optional)	bool
autoReferenced(optional)	bool
overrideReferences(optional)	bool
precompiledReferences(optional)	string array
defineConstraints(optional)	string array
optionalUnityReferences(optional)	string array

The fields includePlatforms and excludePlatforms cannot be used together in the same assembly definition file.

You can specify the Assembly Definition Assets in the references field by using either the name of the assembly or the GUID of the Asset. To use the Asset GUID, the value should take the form GUID:Asset GUID For example, use “GUID:0ec2b662ccc592241854c1b507df8a89”. AssetDatabase.AssetPathToGUID to retrieve the GUID of an Asset.

You can retrieve the platform name strings with the CompilationPipeline.GetAssemblyDefinitionPlatforms() function. (Support for a platform must be installed for the current Editor.)

An Assembly Definition Reference is a JSON object with the following field:

Field	Type
reference	string

The referenced Assembly Definition Asset can be specified by using either the name of the assembly or the GUID of the asset. To use the asset GUID, the value should take the form GUID:Asset GUID, for example “GUID:0ec2b662ccc592241854c1b507df8a89”. AssetDatabase.AssetPathToGUID can be used to retrieve the GUID of an asset.

Example Assembly Definition JSON

MyLibrary.asmdef

{
    "name": "MyLibrary",
    "references": [ "Utility" ],
    "includePlatforms": ["Android", "iOS"]
}

MyLibrary2.asmdef

{
    "name": "MyLibrary2",
    "references": [ "GUID:0ec2b662ccc592241854c1b507df8a89" ],
     "excludePlatforms": ["WebGL"]
} 

---

• New feature in 2017.3 NewIn20173

• Custom Script Assemblies updated in 2018.1

• Additional properties added in 2019.1