Search Unity

Unity 2017.3b feature preview: Assembly Definition Files and Transform Tool

November 22, 2017 in Technology | 7 min. read
Topics covered

As the release of Unity 2017.3 is drawing near, we’d like to show you two nifty features that you might like.

The first feature is Assembly Definition Files. With this feature, you’ll get the option to define your own managed assemblies inside a folder. With well-defined dependencies you’ll ensure that only the required assemblies will be rebuilt, when you make a change in a script, reducing compilation time.

The larger your project grows, the greater the compilation time will inevitably end up being. When iterating on a project this can easily become a nuisance,  so setting up proper assembly definition files should help you work more efficiently and waste less time waiting for scripts to compile.

The second feature is the new Transform Tool. The Transform Tool is a mix of the three current tools; Move, Rotate and Scale suitable for those situations, where easy access to all three is required. A small thing, but also a potential time saver.

You can test out the above features (and more) right now while waiting for the full release of Unity 2017.3, by simply downloading the 2017.3 beta here. Remember to take backups before upgrading your project.

Script Compilation - Assembly Definition Files

Unity automatically defines how scripts compile to managed assemblies. Typically, compilation times in the Unity Editor for iterative script changes increase as you add more scripts to the Project. When you are going through an iterative process you want the builds to compile as fast and smooth as possible.

You can use an assembly definition file to define your own managed assemblies based upon scripts inside a folder. If you separate Project scripts into multiple assemblies with well-defined dependencies, you’ll ensure that only required assemblies are rebuilt when making changes in a script. This reduces compilation times, so you can think of each managed assembly as a single library within the Unity Project.

The figure above illustrates how you can split the Project scripts into several assemblies. If you are only changing scripts in Main.dll, none of the other assemblies will need to recompile. Since Main.dll contains fewer scripts, it also compiles faster than Assembly-CSharp.dll.

Similarly, script changes you make in Stuff.dll will only cause Main.dll and Stuff.dll to recompile.

How to use assembly definition files

Assembly definition files are Asset files that you create by going to Assets > CreateAssembly Definition. They have the extension .asmdef .

You can add an assembly definition file to a folder in a Unity Project to compile all the scripts in the folder into an assembly, and then set the name of the assembly in the Inspector.

Note: The name of the folder in which the assembly definition file resides and the filename of the assembly definition file have no effect on the name of the assembly.

Add references to other assembly definition files in the Project using the Inspector too. The references are used when compiling the assemblies and define the dependencies between the assemblies.

Unity uses the references to compile the assemblies and also defines the dependencies between the assemblies.

You can set the platform compatibility for the assembly definition files in the Inspector. You have the option to exclude or include specific platforms.

Multiple assembly definition files inside a folder hierarchy

If you have multiple assembly definition files (extension: .asmdef) inside a folder hierarchy it will cause each script to be added to the assembly definition file with the shortest path distance.


If you have a Assets/ExampleFolder/MyLibrary.asmdef and a Assets/ExampleFolder/ExampleFolder2/Utility.asmdef file, then:

  • Any scripts inside the Assets > ExampleFolder > ExampleFolder2 folder will be compiled into the Assets/ExampleFolder/ExampleFolder2/Utility.asmdef defined assembly.
  • Any files in the Assets > ExampleFolder folder that are not inside Assets > ExampleFolder > ExampleFolder2 folder would be compiled into the Assets/ExampleFolder/MyLibrary.asmdef defined assembly.

Assembly definition files are not build system files

**Note** : The assembly definition files are not assembly build files. They do not support conditional build rules typically found in build systems.

This is also the reason why the assembly definition files do not support setting of preprocessor directives (defines), as those are static at all times.

Backwards compatibility and implicit dependencies

Assembly definition files are backwards compatible with the existing Predefined Compilation System in Unity. This means that the predefined assemblies always depend on every assembly definition file’s assemblies.
This is similar to how all scripts are dependent on all precompiled assemblies (plugins / .dlls) compatible with the active build target in Unity.

The diagram in Figure 3 illustrates the dependencies between predefined assemblies, assembly definition files assemblies and precompiled assemblies.

Unity gives priority to the assembly definition files over the Predefined Compilation System.

This means that having any of the special folder names from the predefined compilation inside an assembly definition file folder will not have any effect on the compilation. Unity treats these as regular folders without any special meaning.

It is highly recommended that you use assembly definition files for all the scripts in the Project, or not at all. Otherwise, the scripts that are not using assembly definition files always recompile every time an assembly definition file recompiles. This reduces the benefit of using assembly definition files in your project.


In the namespace UnityEditor.Compilation there is a static CompilationPipeline class that you use to retrieve information about assembly definition files and all assemblies built by Unity.

File Format

Assembly definition files are JSON files. They have the following fields: 

Field Type
name string
references (optional) string array
includePlatforms (optional) string array
excludePlatforms (optional) string array


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

Retrieve the platform names by using



"name" : "MyLibrary" ,
"references" : [ "Utility" ],
"includePlatforms" : [ "Android" , "iOS" ]
"name" : "MyLibrary2" ,
"references" : [ "Utility" ],
"excludePlatforms" : [ "WebGL" ]

You can find the Assembly Definition Files Example Project on our forum, and download the 2017.3 beta here.

Transform Tool

One of the other useful features you’ll find in the 2017.3 beta is the new Transform Tool. The Transform Tool is a multitool that contains the functionality of the standard three Move, Rotate and Scale tools. The Transform Tool isn't meant to replace the three standard tools, but to provide a tool for situations where you would want all of the present without having to switch back and forth between them.

To get early access and try out the new Transform Tool coming soon in 2017.3, you can download the Unity 2017.3 beta. Once installed, you’ll have access to this and all of the upcoming features in the next version of Unity.

Enabling the Transform Tool

To begin using the Transform Tool, click the Transform Tool button in the toolbar or press “Y”.

You’ll now have access to the Transform Tool gizmo.


World gizmo

With the pivot rotation set to “Global” mode, you can translate and rotate the GameObject along the global axes.

Axis translation, Plane translation
Axis rotation, Screen Space rotation, Free rotation
Global scaling

Local gizmo

When the pivot rotation is in “Local” mode, you can also scale along local axes.

Local axis scaling

Screen Space Gizmo

If you keep the “SHIFT” key pressed, the gizmo enters Screen Space mode.
In this mode, you can translate and rotate in screen space.

Axis translation, Plane translation, Axis rotation and Global scaling


When you keep the “CTRL” (Win) or “Command” (OSX) key pressed, the unit snapping is activated for:

  • Axes translations
  • Plane translations
  • Axes rotations
  • Axes scaling
  • Global scaling
Plane translation, Axis translation, Global scaling, Axis rotation

Vertex Snapping

When you press and keep the “V” key pressed, the gizmos enters vertex snapping mode.
This way, you can translate your gameobject so one of its vertex is placed on the vertex of another object.

Plane translation, Axis translation, Global scaling, Axis rotation

Get early access to the features now

Both Assembly Definition Files and the Transform Tool are a part of the Unity 2017.3 beta together with new improvements to the particle system, an updated Crunch texture compression library and much more. Test compatibility with your current project or play around with the new features by downloading the beta. You also still have time to be a part of this round of beta sweepstakes too for the chance of winning one of three Acer Windows Mixed Reality headsets with Motion Controllers, sponsored by our friends at Microsoft - read more about that here.

November 22, 2017 in Technology | 7 min. read
Topics covered