Search Unity

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

, November 22, 2017

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


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.


26 replies on “Unity 2017.3b feature preview: Assembly Definition Files and Transform Tool”

Programmer here – the assembly definition file is exactly what we needed!

However, the assembly generated always use the unity Assets directory as its root, i.e. if I create an assembly def file in /project-root/assets/MyModule, I want the assembly to point to /project-root/assets/MyModule instead of /project-root/assets; This makes the assembly files harder to browse as you have to click and expand some extra folders.

Great feature! I love it!

How about this, stop integrating and go back to the 4.6.8 style editor. There was nothing wrong with it now we have all this crap piled up on top of crap instead of fixing tons of issues. I can see adding more stuff into the engine such as a better renderer take a look at Unreal and get some ideas on how you can improve that. Another thing Vertex Snapping that’s a new feature?? We had that back in 4.6.8 anyone on 5.x.x try it Shift V and move your object around super new.. Also whats the point of having a zoom in the game window? That’s what the scene view was for I thought. Its not all bad though Unity3d is amazing your just overcompensating in the wrong areas.

Instead of a new cluttered transform tool, wouldn’t it be far more productive to instead have keyboard shortcuts for moving, rotating and scaling in specific axes? Say, something like what’s in Blender? How about letting me directly input the transformation values by using those keyboard shortcuts? And how about making a nicer gizmo for the 2D mode, and a 2D mode for the transform inspector?

I get that I can probably create some of these tools for Unity myself (In fact, I’ve found some assets that already enable some of those features, and I even created a transform inspector that allows you to switch between 2D and 3D modes: would you like to hire me to do this for you?), but I’d much rather have some of them already built into Unity, so I don’t have to manually add all of these custom editor scripts into all of my projects, or (And I’d love to see this implemented regardless) allow us to more easily/further modify the editor GUI. How about letting us extend or modify all of the existing editors? I’ve been struggling with Your extremely user unfriendly Animator editor with no zooming feature or curved transition lines for literally 5 years now.

Ah, interesting, looks like Unity 2017.3 Beta breaks my 2D/3D transform inspector. Thanks!

Good job, Team Unity, Good job!

The “splitting up compilation into different DLLs” thing is superseeded by the immense speed improvement you get from just ditching mono compiler completely and compile all source code with MS Visual Studio. For us, this got compile times down from about 30 seconds to under 2 seconds. So I don’t see a point about the assembly definition files, except for “we want to support Editor – Mac/Linux compilation of code”, which is of no interest to probably 95% of devs?

About the transform tool: I never had problems with the current tool, but I guess you guys had a reason to change it…? Probably?

assembly definition is very nice but the new transform tool … sould be better.
No axial scale gizmo when in global or screen mode and the gizmo is drawn on top of the object with no indication of depth – confusing.

Hey das, out of curiosity: why do you want to scale in screen mode? If you think about it (simple example), rotating a cube and then scaling in screen space would skew it, making it another shape. That’s… doable, I guess, but it would require to modify the underlying mesh because you can’t describe that just by using the Transform values. Same goes for scaling in global space.
So, I’m curious: what’s your use case?

Well, strictly speaking, you CAN do a skew transform using the same underlying transformation matrix that objects have. That being said, I can’t even begin to imagine the math entailed in converting a screen-space skew operation into an object-level transformation matrix. And I do have to agree, why would you even want to?

If assembly definition files work for the switch between editor and play mode, and can continue to run through recompiles in editor mode, we could simplify Scene Fusion, where it will allow people to drop off for these events while keeping everyone connected.

External tools can use this system and I guess using only the meta of the folders may work great within Unity but will cause a lot of confusion when using some “advanced” workflows, e

The new Transform tool is a great addition! It’s really improved the workflow. Kudos to whomever thought of this and implemented it!

Nice features. One question about the Script Assemblies. How will GUID referencing work in that case? For example, I have a component which references the original script from the folder and another reference which references the script from the generated DLL.

GUID referencing is actually unaffected. The GUID reference goes to the C# script asset which is still there. So from the perspective of the asset database, nothing has changed. It isn’t aware of what the script compilation pipeline does with the C# scripts it is being fed.

Thanks Rene.
I’ll give it a try then. Had some problems in the past with exactly that, but it was in experimential state back then, so maybe it has been improved (or I did it wrong ^^).

Sometimes simple improvements are useful than complex ones. Finally a super awesome all in one Gizmo tool in Unity! Thx Unity Team!

Comments are closed.