Assembly Definition Files (asmdef) in Unity is a powerful feature that helps manage and organize your codebase.

💡

Essentially, it's the process of defining logical containers for your scripts, helping you to streamline and control the way your code is compiled.

Let's dive into the world of Assembly Definition and see how it can elevate your Unity projects! 🚀

Absolutely! Here's the revised version with emojis added for a more engaging read:

Understanding Assemblies in Unity: A Recap 🧠🎮

An Assembly in Unity is a C# code library 📚 containing compiled classes and structs defined by your scripts, and it includes references to other assemblies.

By default, Unity compiles most of the game scripts into a predefined assembly called Assembly-CSharp.dll. While this works fine for small projects 🌱, it has drawbacks:

Compilation Time ⏱️: Any change in one script leads to the recompilation of all scripts, increasing the wait.
Access Control 🔐: Any script can directly access types in other scripts, making code refactoring tricky.
Platform Compatibility 🎮: All scripts are compiled for all platforms, lacking customization.

To tackle these issues, defining your assemblies allows:

Modularity 🧩: Organize your code for better reusability.
Controlled Access 🔒: Custom assemblies can only access designated ones.
Separation of Concerns ➗: By splitting code into assemblies like Main, Stuff, and Library, changes in one area won't affect others. Reusable Library code can be ported to other projects 🔄.

In essence, defining assemblies leads to a more organized and maintainable codebase, enhancing both development and execution within Unity projects.

Why Assembly Definition? It's all about efficiency and control. Reduce compilation time, manage dependencies, and enjoy a cleaner codebase, whether you're working on an indie game or a commercial project .

Example Diagram of Assembly Functionality from Unity Documentation 📊

This diagram illustrates how to split code into different assemblies. Because Main references Stuff but not vice versa, changes in Main won't affect Stuff. Library, not depending on others, can be reused elsewhere.

Defining Assemblies in Unity: A Step-by-Step Guide 🧩

Create organized and efficient Unity projects by defining assemblies:

Create Folders for Assemblies : Divide code into folders for each assembly.
Create Assembly Definition Assets : Define properties in each folder.
Compilation Process : Unity compiles scripts into assemblies using the asset's name and settings, including child folders.
Non-Child Folder Inclusion: Craft an Assembly Reference asset to include non-child folder scripts.
Compilation Order: Unity sets the compilation sequence based on dependencies. Manual configuration is not possible.

By defining assemblies, you manage dependencies with precision and create a modular environment. Embrace this vital practice for organized and efficient Unity projects .

Assembly Definition Properties Explained 🛠️

Below are the key properties you can set when defining an assembly in Unity:

Name

This is the unique name assigned to the assembly, without including a file extension. It's crucial that each assembly name is distinctive across the Project. Utilizing a reverse-DNS naming style can minimize potential conflicts, especially if the assembly is shared across multiple Projects. Note: Unity's default value for this field is the name assigned to the Assembly Definition asset, but it's modifiable.

Allow 'unsafe' Code

Activate this option if the assembly contains any scripts using the C# unsafe keyword. Enabling this prompts Unity to invoke the /unsafe option with the C# compiler during assembly compilation.

Auto Referenced

This property determines whether the predefined assemblies should reference this Project assembly. Disabling Auto Reference means Unity won't reference the assembly automatically during compilation, though it doesn't affect its inclusion in the build.

Example: Creating a Specialized Editor Tool 🛠️

Imagine you're working on a large Unity project 🎮, and you've created a specialized editor tool that helps with level design.

This tool is meant only for the development phase 🔧 and is not intended to be part of the final game build 🚀.

You might decide to organize the scripts related to this tool into their own assembly by creating an Assembly Definition file and placing all the editor tool scripts in the same folder 📂.

Now, here's where Auto Referenced comes into play:

If Auto Referenced is Enabled ✅: Unity will automatically include references to this assembly when compiling other scripts in your project. This means that any other script in the project can directly access the classes and methods in your editor tool assembly, even if those other scripts are part of the final game build.
If Auto Referenced is Disabled ❌: Other scripts in your project will not automatically have access to the classes and methods in your editor tool assembly. This can be very useful in this scenario because you can ensure that no game scripts accidentally depend on something that's meant only for development.

By disabling the Auto Referenced property, you can effectively isolate the editor tool assembly from the rest of your project. This minimizes the risk of accidental dependencies, helps keep the final build clean , and can even slightly reduce compile times ⏱️, as Unity doesn't have to check this assembly when compiling other code.

It's a small detail, but one that can have a meaningful impact on your development workflow and final product, especially in complex projects with many interdependencies 🧩.

No Engine References:

When enabled, Unity excludes references to UnityEditor or UnityEngine during the compilation of the assembly.

When to Use "No Engine References" 🔗

Creating a Pure C# Library: If you are developing a library that is pure C#, and doesn't depend on Unity's engine features or editor functionalities, enabling "No Engine References" ensures that Unity will not include references to UnityEngine or UnityEditor. This can make the assembly more portable and usable in non-Unity contexts 🎓.
Avoiding Unnecessary Dependencies: In larger projects, managing dependencies becomes more complex. By excluding engine references, you can minimize dependencies, making the code easier to maintain and reducing potential conflicts or compatibility issues 🔧.
Optimizing Compilation: Excluding unnecessary references can also help in optimizing the compilation process. By not including references that your assembly doesn't require, you may speed up compilation times ⏱️.
Building Plugins for Other Environments: If you are developing plugins or modules that are intended to be used outside of Unity (e.g., in other development environments or tools), then excluding Unity-specific references ensures that your code doesn't accidentally rely on Unity-specific functionalities 🛠️.
Reuse Across Different Projects 🔄: If you intend to create a library or module that you want to use across different projects, not just within Unity, enabling "No Engine References" ensures that the assembly doesn't have unnecessary Unity dependencies. This can make the assembly more versatile.

Just be cautious, as misusing this option could lead to compilation errors if your code does actually depend on Unity engine features. Always test thoroughly!

Override References 🐍

Enable this to manually define the dependencies on precompiled assemblies (a (.dll) for this particular assembly.

When activated, the Inspector displays the Assembly References section to specify the references. By default, assemblies in your Project reference all added precompiled assemblies. Enabling Override References restricts the assembly to only refer to those specified under Assembly References.

Note: To prevent automatic referencing of a precompiled assembly by Project assemblies, you can deactivate its Auto Referenced option. Refer to the Plugin Inspector for more details.

Example: Creating a Specialized Utility Library 🛠️

Imagine you're working on a large Unity project, and you have created a specialized utility library that's meant to handle mathematical calculations for various game mechanics. This utility library doesn't need to interact with the Unity Engine directly, and you've also imported a third-party numerical library that you want to use in this assembly.

Create the Utility Assembly: First, you create an assembly called GameMathUtilities and place all related scripts into a folder with an Assembly Definition asset.
Import the Third-Party Library: You import the third-party numerical library (e.g., MathNet.Numerics.dll) into your Unity project.
Enable Override References: Inside the Assembly Definition asset for GameMathUtilities, you enable the "Override References" option. This allows you to manually control which precompiled assemblies this assembly depends upon.
Specify the References: In the Assembly References section that now appears, you manually select the MathNet.Numerics.dll and any other required dependencies, but exclude unnecessary Unity engine references.
Code Your Utility Functions: You then write your mathematical utility functions, utilizing classes and methods from MathNet.Numerics.
Prevent Auto Referencing if Needed: If you don't want other assemblies in your project to automatically reference this third-party library, you can deactivate its "Auto Referenced" option, as noted in the Plugin Inspector.

Root Namespace

This property sets the default namespace for scripts within this assembly definition. If Rider or Visual Studio is used as the code editor, they will automatically apply this namespace to any newly created scripts in this assembly definition.

Understanding and configuring these properties help you create assemblies tailored to your Project's needs, providing a level of control that enhances code organization and efficiency. 🎮💻

Now let’s Dive deeper into all the Assembly properties

Default Constraints: Conditionally Including an Assembly 🧙‍♂️

In Unity, you might have scenarios where an assembly should only be included in specific builds or configurations of your game.

This is where Default Constraints come into play, offering you the magical ability to control the compilation and inclusion of an assembly based on preprocessor symbols 🎩✨.

‣

Here's how to set up Default Constraints:

Select the Assembly Definition 📁: Open the assembly you want to conditionally include, and view its properties in the Inspector 🔍.
Define Constraints Section 🧩: Navigate to the "Define Constraints" section. Here, you can specify the symbols that control whether the assembly is included or not 🚀.
Add a Symbol ➕: Click the + button to add a new symbol. Enter the symbol name, and optionally use an exclamation point (!) to negate the symbol. For example, !UNITY_WEBGL would include the assembly when UNITY_WEBGL is NOT defined ❗.
Apply Changes 💾: Don't forget to click "Apply" to save your settings ✅.
Symbol Options 🎚️:

Custom Symbols 🏷️: These can be defined in the "Scripting Define Symbols" setting, found in the Player section of your Project Settings 🎮.
Unity-Defined Symbols 📜: Unity provides some built-in symbols. Refer to the Platform Dependent Compilation for a complete list 📖.
Version Defines 📚: You can also use symbols defined in the "Version Defines" section of the Assembly Definition asset 🔗.

Constraints on Scripts 📝: It's worth noting that symbols defined in scripts are not considered when determining if a constraint is met ❌.

Use Cases and Benefits 🏆🎮

Platform-Specific Features 🖥️📱: Include an assembly only for specific platforms or exclude it from others.
Development vs Production 🛠️💼: Enable or disable debugging or testing assemblies based on build configurations.
Optimization 🚀: Reduce build size and complexity by including only what's needed for each scenario.

Assembly Definition Reference Properties: A Guided Overview 🎛️🔗

Assembly Definition Reference is a vital part of the Unity development ecosystem, allowing you to create references between different Assembly Definitions 🏗️.

It's like building bridges between various parts of your code, creating a coherent and interconnected structure 🌉.

Here's a look at the essential properties that define how Assembly Definition Reference works in Unity:

1. Use GUID: A Robust Reference 🎫✅

The "Use GUID" property controls how Unity serializes the reference to the Assembly Definition asset 📝.

Enabled: Unity saves the reference as the asset's Global Unique Identifier (GUID) 🌐.
Disabled: The reference is saved using the Assembly Definition name 🏷️.

Why use GUID? It's a best practice to enable this option because it provides flexibility when changing the name of an Assembly Definition asset 😊. Even if you rename the asset, the GUID remains constant, meaning you won't have to update other Assembly Definitions and References that reference it 🔄. It’s like having a permanent address for your code, no matter how many times you change its name 🏠.

2. Assembly Definition: The Reference 🎯

This property specifies the particular Assembly Definition asset that you want to reference 🧩. It's like selecting a destination for your bridge 🌉.

Selection: You can choose the required Assembly Definition from your project to be the reference point 📌.
Purpose: By selecting an Assembly Definition, you are including the scripts in that folder (and child folders) in the referenced Assembly Definition 📂. This means they won't create a new assembly, but become part of the existing one 🧰.

Child Folders: An Important Note 🧒

Scripts in child folders will be included in the referenced Assembly Definition.

However, if they have their own Assembly Definition or Assembly Definition Reference asset, they will act independently ✂️.

Conclusion: Building Coherent Code Structures 🏗️

Assembly Definition Reference properties in Unity provide a powerful way to organize and interconnect your codebase 🔧. By understanding and utilizing these features, you can craft more modular, maintainable, and efficient projects 🛠️💡. Happy bridging! 🎮

Platforms in Assembly Definition: A Targeted Approach 🎯

When working on a game or application in Unity, one of the core considerations is the platform you're targeting 🎮.

Whether it's PC, mobile, web, or console, your code needs to be optimized and compiled to work on the intended platform.

This is where Platforms in Assembly Definition comes into play, ensuring that your code is ready to run smoothly on various devices 📱.

1. Selecting Platforms: Choose Your Destination 🌍✅

In Assembly Definition, you have the ability to select the specific platforms you want the assembly to be compiled for 🛠️.

How? In the Inspector, under the Platforms section, you can find a list of all the available platforms 📋. Simply check the boxes next to the platforms you want to target 🎯.
Why? By selecting specific platforms, you ensure that the assembly is optimized and only includes code relevant to those platforms, improving performance and reducing build size 🚀.

3. Platform-Specific Code: Tailoring Your Approach 👚

Sometimes, you may have code that's specific to a particular platform, like mobile touch controls 📱 or VR functionalities 🕶️.

How? You can use preprocessor directives like #if UNITY_ANDROID or #if UNITY_IOS in your scripts to include or exclude code blocks for specific platforms 📝.
Why? This ensures that only the relevant code is compiled and included in the build, maintaining efficiency and coherence across different platforms 🌐.

Version Defines in Assembly Definition: Managing Dependencies 🔧

Version Defines in Assembly Definition is a powerful feature in Unity that allows you to conditionally compile parts of your code based on the version of specific precompiled assemblies (like plugins or libraries).

This functionality ensures that your code is compatible with different versions of dependencies, creating a smoother and more robust development experience 🧩💼.

1. Setting Up Version Defines: Your Key to Compatibility 🔑

How? Within the Assembly Definition file, locate the Version Defines section. Here, you can add the precompiled assembly's name and specify the version range (or specific version) you want to target 🎯.
Why? By defining specific versions, you can write code that only compiles if the specified assembly's version matches the range you set. This way, you can handle different versions of the same assembly seamlessly, ensuring compatibility and reducing potential errors 🚫🐛.

3. Benefits of Version Defines: Adaptable and Efficient 🌱🏎️

Adaptability: Version Defines enables your code to adapt to different versions of dependencies, creating a more flexible codebase 🌳.
Efficiency: By compiling only the relevant code for the specific version, you enhance performance and reduce potential conflicts and maintenance overhead 🧹💨.
Collaboration: If you're working with other developers using different versions of the same assembly, Version Defines helps to harmonize the development environment 🤝💻.

Getting Assembly Information in Build Scripts: A Powerful Insight Tool 🛠️

In complex Unity projects, managing and understanding the interplay of various assemblies can be crucial.

Unity offers a handy feature that allows developers to dig into the assembly information, particularly useful during the build process.

This feature revolves around the CompilationPipeline class, located within the UnityEditor.Compilation namespace.

What Does It Do? 🤔

The CompilationPipeline class provides access to information about all assemblies built by Unity for a project.

This includes the assemblies created based on Assembly Definition assets. By employing this class, developers can gain insights into the compilation details, relationships, and the overall structure of assemblies within the project.

A Practical Example 📜

Consider a situation where you want to list all the current Player assemblies in a project. Unity enables this through a script utilizing the CompilationPipeline class. Here's a code snippet illustrating this:

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);
        }
    }
}

This script lists all the current Player assemblies in the Unity Console, offering a clear view of what's compiled into the Player build.

By invoking the menu item "Tools/List Player Assemblies in Console," you will see a list of all Player assemblies in the Console window.

Why Use It? 🎯

Understanding and managing assembly information is crucial for debugging, optimization, and ensuring proper dependencies in complex projects. By leveraging the CompilationPipeline class:

Enhance Debugging: Quickly identify what assemblies are present and how they are related.
Streamline Development Workflow: Integrate the assembly listing into custom tools or extensions within Unity.

Conclusion: Assembly Definitions in Unity - Crafting Cohesive Code Architecture 🏰

Assembly Definitions have surfaced as an indispensable feature within Unity, offering a robust and elegant solution to manage and organize code. Far more than a simple housekeeping exercise, their impact on both development and execution efficiency is transformative.

Key Takeaways 📘

Modularity: Assembly Definitions enable developers to carve out distinct code libraries, promoting reusability and efficiency across different projects. Say goodbye to monolithic codebases and embrace a compartmentalized and logical code structure. 📦
Controlled Access: By defining assemblies, developers wield the power to manage dependencies, enforce access control, and foster a more secure and maintainable code environment. No more wild cross-referencing or unwanted dependencies. 🗝️
Performance Boost: Faster compilation times, more controlled execution, and flexibility in platform compatibility translate into real time-saving benefits. All these lead to quicker iterations and more fluid development processes. 🚄
Precision and Customization: From defining constraints to specifying platform compatibility, Assembly Definitions allow precise customization that fits the project’s needs. This granularity ensures that your code functions exactly how and where you want it to. 🎛️

Embrace the Future of Code Management 🤖

In an era where codebases are growing in complexity, Assembly Definitions come as a beacon of organization, allowing the art of coding to flourish without being entangled in a web of complexity.

They align not just with the technical needs but also with the philosophy of clean and sustainable coding practices. 🌳

By integrating Assembly Definitions, Unity developers not only enhance their current workflow but also future-proof their projects, making them more adaptable, maintainable, and efficient.

This is not just a feature; it's a fundamental paradigm shift in how we think about and manage code within Unity.

In the end, Assembly Definitions are about empowering developers, giving them the tools and flexibility to create, innovate, and thrive.

So, gear up and redefine your Unity project with the art of Assembly Definitions. It's not just a step in the right direction; it's a leap towards excellence! 🎮

Happy developing, and may your code always compile smoothly! 🛠️

Resources

Unity Assembly - Official Documentation
Assembly Definition video tutorial - Infallible code

✍️ Author

Marco Mignano 👋 ➡️ Passionate Unity Game Developer Marco - coding aficionado, video game enthusiast, and self-proclaimed piazza addict. Constantly conquering new challenges, one line of code at a time. Got an exciting project? Let's make your game next game together!

Contact: marco@gladiogames.com

Unity Assembly Definitions Explained: How to Organize and Control Your Code