In Unity, creating an assembly reference fundamentally involves establishing an Assembly Definition Asset (.asmdef file). This asset defines a distinct code assembly within your project, enabling better code organization, faster compilation times, and explicit dependency management between different parts of your codebase.
The process of setting up these references begins with creating the Assembly Definition Asset itself, and then configuring its properties to include dependencies on other assemblies.
Steps to Create an Assembly Definition Asset and Configure References
Follow these steps to create an Assembly Definition Asset and establish references to other assemblies:
-
Create the Assembly Definition Asset:
- Navigate to the Unity editor menu:
Assets > Create > Assembly Definition. - This action will generate a new
.asmdeffile in your Project window. It's recommended to place these files strategically, often at the root of a folder containing the scripts that belong to that specific assembly. For example, if you have aPlayerfolder for player-related scripts, you might place aPlayer.asmdefinside it.
- Navigate to the Unity editor menu:
-
Select the New Assembly Definition:
- Locate the newly created
.asmdeffile in your Project window and select it. This will display its properties in the Inspector window.
- Locate the newly created
-
Set the Properties in the Inspector Window, as Necessary:
- With the
.asmdeffile selected in the Inspector, you can configure various properties that define how this assembly behaves. This includes its name, version compatibility, and crucially, its dependencies.
Configuring Assembly References
To establish a direct reference from this new assembly to another existing assembly (another
.asmdeffile), you will use the Inspector window for your selected Assembly Definition Asset:-
Access the References List: Look for the "Assembly Definition References" section within the Inspector. This is where you declare which other
.asmdeffiles your current assembly depends on. -
Add a New Reference: Click the small plus (
+) button located at the bottom right of the "Assembly Definition References" list. This will create a new empty slot. -
Assign the Reference:
- Drag and Drop: Drag the desired target
.asmdefasset (e.g.,Utilities.asmdefif your Player assembly needs common utility functions) from your Project window directly into the new slot. - Object Picker: Alternatively, click the small circle icon next to the empty slot to open the Object Picker, then search for and select the
.asmdeffile you wish to reference.
- Drag and Drop: Drag the desired target
-
Apply Changes: Unity automatically processes changes to
.asmdeffiles, so simply configuring these properties will update your project's assembly structure.
- With the
Understanding Assembly Definition Properties
The Inspector window for an Assembly Definition Asset offers several important properties:
| Property | Description |
|---|---|
| Name | The identifier for your assembly. This should be unique within your project. |
| Allow Unsafe Code | Enables the use of unsafe C# code blocks within this assembly. |
| Auto Referenced | If checked, this assembly is automatically referenced by any .asmdef files created without explicit references, and by the "Assembly-CSharp" assembly (the default assembly for scripts not in an .asmdef). Unchecking it isolates the assembly. |
| Override References | If enabled, this allows you to explicitly list all referenced assemblies. If disabled, Unity will automatically reference all .asmdef files in subfolders, which can sometimes lead to circular dependencies. Generally, enabling this provides more control. |
| Assembly Definition References | The most crucial section for creating references. Here, you list other .asmdef files that this assembly will depend on. Code in this assembly can access types and members from the referenced assemblies. |
| Version Defines | Allows you to define compilation symbols based on package versions, enabling conditional compilation. |
| No Engine References | Prevents this assembly from referencing Unity's core engine assemblies (e.g., UnityEngine.CoreModule). Useful for creating pure C# libraries or editor-only tools. |
| Platform Compatibility | Determines which platforms this assembly should be compiled for. You can include or exclude specific platforms (e.g., only for Editor, or exclude Mobile). |
Benefits of Using Assembly References
Utilizing Assembly Definition Assets and their references offers significant advantages:
- Faster Iteration Times: By dividing your code into smaller, more isolated assemblies, Unity only recompiles the affected assemblies when you make changes, dramatically reducing compile times, especially in large projects.
- Clearer Dependencies: Explicitly defining references forces a structured approach to your codebase, making it clear which parts of your project depend on others. This prevents unintended dependencies and improves maintainability.
- Better Code Organization: Promotes modular design, as related scripts are grouped into their own assemblies.
- Reduced Build Sizes: For platform-specific builds, Unity can strip out assemblies not relevant to the target platform, potentially reducing application size.
By following these steps, you can effectively create and manage assembly references in Unity, leading to a more efficient and organized development workflow.
[[Unity Assembly Definitions]]
