Assemblies and asmdef files

Quick overview

An assembly is a compiled .NET unit. By default, Unity puts many scripts in predefined assemblies. An Assembly Definition (.asmdef) lets you split project code into named assemblies that can reference one another explicitly. This can improve isolation, testing and incremental compilation, but it is not automatically faster for every project.

How the pieces fit

The .asmdef file defines the compilation boundary for scripts in its folder and nested folders, except where another assembly definition takes over. A namespace controls type names; it does not decide assembly membership.

• DirectoryAssets/

  • DirectoryScripts/

    • DirectoryGameplay/

      • HCSTech.Gameplay.asmdef
      • Health.cs
      • Inventory.cs
    • DirectoryUI/

      • HCSTech.UI.asmdef
      • InventoryView.cs
  • DirectoryEditor/

    • HCSTech.Editor.asmdef
    • BuildTools.cs

In this example UI may reference Gameplay, but gameplay logic should not need to reference UI. That direction makes it easier to run gameplay tests without pulling in presentation code.

Create a definition in Unity

1. In the Project window, right-click the folder and choose Create > Scripting > Assembly Definition.
2. Choose a stable assembly name, such as HCSTech.Gameplay. Keep it consistent with package and project conventions.
3. For assemblies that depend on it, add HCSTech.Gameplay to their Assembly Definition References in the Inspector.
4. Keep editor-only tooling in an Editor assembly and restrict its platforms to Editor as needed.
5. Run tests and enter Play mode. Missing references or circular dependencies often become visible immediately.

Common pitfalls

Symptom	Likely explanation	What to check
Type exists but is not visible	Missing assembly reference	Inspector references and platform filters
Two assemblies refer to one another	Circular dependency	Move shared contracts into a third assembly
Tests cannot see an internal type	Access boundary	Prefer testing public behavior; use intended test visibility only when necessary
Editor APIs fail in player builds	Wrong assembly/platform	Editor-only assemblies and conditional compilation

Do not add asmdefs everywhere

Each boundary adds references and maintenance. Start where modules have a clear responsibility or compilation and testing requirements justify it.

Namespace versus assembly

namespace HCSTech.Gameplay in a .cs file and HCSTech.Gameplay.asmdef are allowed to share a name, but they are separate mechanisms. A single assembly can contain several namespaces, and a namespace may span multiple assemblies. The compiler and Unity resolve dependencies through assemblies, not through folder names alone.

When to use it

Assembly definitions make sense when a Unity project has reusable modules, independent tests, editor tooling, or large teams. In a small prototype, ordinary scripts can be simpler. Review assembly references alongside your test setup before reorganizing a mature project.

See also Namespaces and Unity script lifecycle.