Special folders and script compilation order
Assembly Definition properties

Assembly Definitions

Create Assembly Definitions to organize the 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 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. (Scripts in subfolders are included unless the subfolder has its own Assembly Definition.) You can think of each of these managed assemblies 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 defining the Assembly Definition properties. You can 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 by selecting the asset file. You can also edit the JSON directly using an external editor. See Assembly Definition File format for information about the JSON syntax.

Why use Assembly Definitions

When you separate your code into assemblies having well-defined dependencies, Unity reduces compilation time by only rebuilding the dependent assemblies when you make a change to a script. Assembly Definitions can also help you manage dependencies in projects containing 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 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 not strictly required, Unity recommends that whenever you use Assembly Definitions in a project, you do so for all of the code in your project. Otherwise, when you change scripts in one of the predefined assemblies, Unity must still recompile all the code in your project, since the predefined assemblies automatically depend upon any assemblies you create using an Assembly Definition.

The following figure illustrates a Project split into several assemblies:

Predefined versus manually defined assemblies
Predefined versus manually defined assemblies

By default, Unity compiles almost all project scripts into the Assembly-CSharp.dll managed assembly. The above example shows a project 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 code in Stuff.dll changes, Unity only needs to recompile Main.dll and Stuff.dll, not ThirdParty.dll or Library.dll.

Note: You can find out where Unity compiles a particular C# file by selecting the script file in the Project window and looking at the Assembly Information listing in the Inspector:

A script in the Assembly-CSharp-Editor.dll predefined assembly
A script in the Assembly-CSharp-Editor.dll predefined assembly

How to use Assembly Definitions

Add Assembly Definition Assets to folders in a Unity Project in order 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:

In the Project window, select the folder in which you want to place the Assembly Definition.

  1. Create the Assembly Definition Asset using the menu: 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.
  2. Select the new Assembly Definition you created.
  3. Set the properties in the Inspector window, as necessary.

You can only create one Assembly Definition per folder. If you create an Assembly Definition in a subfolder of a folder that already has an Assembly Definition, 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.

Version defines

You can 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, click 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 at version define, the following properties appear:

This is what Version defines look like in the Inspector. In this example, there are two active Version defines.
This is what Version defines look like in the Inspector. In this example, there are two active Version defines.
Property Description
Resource Use this drop-down list to select the Package or Module you want to set a define for. The list contains all active Packages and Modules in the Project.
Define The name you want this define to have. This define is only set if the expression below 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 (plugins / .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.

Figure 3 - Assembly dependencies
Figure 3 - Assembly dependencies

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

  1. By default, assemblies created with Assembly Definition Assets are referenced by the predefined assemblies. You can turn this off by unchecking the Auto Referenced option in the Inspector for an Assembly Definition Asset. See Assembly Definition properties.

  2. Likewise, precompiled assemblies (plugins) are automatically referenced by both the predefined assemblies and assemblies created with Assembly Definition Assets. You can turn this default behavior off by unchecking the Auto Referenced option in the Inspector for the plugin. See Plugin Inspector.

  3. When you turn off Auto Referenced for a plugin, 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 plugin. See Assembly Definition properties.

Note: if you turn off the Auto Referenced option for precompiled assemblies or assemblies created with Assembly Definition Assets, 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 are most likely to notice this change in special treatment when you use Editor folders, which can often 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 probably don’t belong. To handle Editor folders, you can take one of the following approaches:

  • 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. You can designate that Unity build a test assembly by checking the Test Assemblies option in the Assembly Definition Asset properties. Setting this property does the following:

  • Prevents the predefined assemblies from referencing the test assembly
  • Excludes the test assembly from builds
  • Adds a reference to the NUnit assembly

Note: Use BuildOption.IncludeTestAssemblies in your building script to include a testing assembly in a Release or Development buildA development build includes debug symbols and enables the Profiler. More info
See in Glossary
. This only includes the assemblies in your build and does not execute any tests.

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 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.)

Example Assembly Definition JSON

MyLibrary.asmdef

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

MyLibrary2.asmdef

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

  • 2019–03–07 Page amended with editorial review

  • New feature in 2017.3 NewIn20173

  • Custom Script Assemblies updated in 2018.1

  • Additional properties added in 2019.1

Did you find this page useful? Please give it a rating:

Special folders and script compilation order
Assembly Definition properties