Skip to Content

Assembly Definition & Namespaces

Last modified by Maarten Struijk Wilbrink on 2026/07/21 10:59

This page explains how to keep a Unity 6 project modular with Assembly Definitions (.asmdef) and namespaces. Used together, they reduce compile time, prevent name clashes, and make code easier to reuse.

For XR/VR support: sosxr@fsw.leidenuniv.nl. For general lab support: labsupport@fsw.leidenuniv.nl.

Why use Assembly Definitions?

By default, Unity compiles all your scripts into a few large predefined assemblies. When you change one script, Unity recompiles everything. Assembly Definitions split your code into smaller, isolated assemblies so only affected assemblies recompile.

Benefits:

  • Faster iteration in large projects.
  • Clearer dependencies between features.
  • Easier reuse of code across projects.
  • Test code can live in separate test assemblies that do not ship in the player.

Creating an Assembly Definition

  1. In the Project window, select the folder containing the scripts you want to group.
  2. Choose Assets > Create > Scripting > Assembly Definition.
  3. Name the asset after the folder or feature, e.g. Solo.Experiment.
  4. Select the .asmdef and set its properties in the Inspector:
     

    • Name: the assembly name. Use a clear, project-level name.
    • Root Namespace (optional but recommended): the default namespace Unity suggests for new scripts in this folder, e.g. Solo.Experiment.
    • Platforms: leave as Any Platform for runtime code, or select only Editor for editor tools.
    • Auto Reference: disable if you want other assemblies to reference this one explicitly instead of automatically.
    • Override References: enable when you need to reference precompiled DLLs or package assemblies manually.
    • Version Defines: add symbols that are defined only when a specific package or Unity version is present; useful for conditional compilation.
    • Assembly Definition References: add other .asmdef assets this assembly depends on.

For the full inspector reference, see Assembly Definitions.

Assembly Definition References (.asmref)

If you want scripts in several folders to belong to the same assembly, create an Assembly Definition Reference in each folder:

  1. Assets > Create > Scripting > Assembly Definition Reference.
  2. In the Inspector, point it to the target .asmdef.
  3. All scripts in that folder and its subfolders (that do not have their own .asmdef or .asmref) become part of the referenced assembly.

This is useful for test folders (Tests/Editor, Tests/Runtime) that should compile against the same production code, or for editor-only folders that should share an editor assembly.

Editor-only and test assemblies

  • Editor-only assembly: create an .asmdef, set Platforms to Editor only. This keeps editor tools out of player builds.
  • Test assembly: create an .asmdef with the Test Assemblies option enabled, or use the Tests > Test Assembly Folder template. It must reference UnityEngine.TestRunner and UnityEditor.TestRunner.

Refer to the Test Framework documentation for details.

Reference rules and limitations

  • Custom .asmdef assemblies cannot reference Unity's predefined assemblies (Assembly-CSharp, etc.). References must be explicit.
  • Cyclic references are not allowed; refactor or merge mutually dependent code into one assembly.
  • Enabling Use GUIDs for references lets you rename .asmdef files without breaking references.

Namespaces

Namespaces prevent class-name clashes as the project grows. A good rule of thumb: match the namespace to the folder or assembly root namespace, e.g. Solo.Experiment.Stimuli.

Example:
namespace Solo.Experiment.Stimuli
{
   public class StimulusController : MonoBehaviour { }
}

You can use modern C# file-scoped namespaces to keep files short:
namespace Solo.Experiment.Stimuli;

public class StimulusController : MonoBehaviour { }

For the official guidance, see Naming scripts and namespaces.

Suggested folder layout

For a feature called Stimuli:

  • Assets
    • Stimuli
      • Scripts
        • Stimuli.asmdef  (Root namespace: Solo.Experiment.Stimuli)
      • Tests
        • Editor
          • Stimuli.Tests.Editor.asmref  (references Stimuli.asmdef)
        • Runtime
          • Stimuli.Tests.Runtime.asmref (references Stimuli.asmdef)

Each folder with its own .asmdef becomes a separate assembly; use .asmref for test folders so they compile against the same production code.

See also

Resources