Unity] Assembly Definition

Unity의 **Assembly Definition(어셈블리 정의)**은 프로젝트의 컴파일 시간을 줄이고, 코드의 모듈화와 의존성 관리를 돕기 위한 기능이다. Unity 2017.3 이후 버전부터 제공되며, 대규모 프로젝트에서 특히 유용하게 사용된다. 이 글에서는 Assembly Definition의 개념, 사용하는 이유, 설정 방법, 그리고 주의할 점에 대해 정리한다.

---

1. 어셈블리 정의란?

Unity의 기본 빌드 파이프라인은 Assets 폴더 내부의 스크립트를 전부 **하나의 어셈블리(Assembly-CSharp.dll)**로 묶어 컴파일한다. 이 방식은 프로젝트가 작을 때는 문제가 없지만, 스크립트가 수백 개 이상으로 늘어나면 컴파일 속도가 현저히 느려지고, 변경되지 않은 스크립트도 다시 컴파일하는 문제가 발생한다.

Assembly Definition(asmdef) 파일은 해당 디렉토리 이하의 스크립트를 별도의 어셈블리로 분리해서 컴파일하도록 Unity에 지시하는 역할을 한다. 즉, 코드의 물리적 분리를 통해 의존성과 컴파일 단위를 명시적으로 분리할 수 있는 도구이다.

---

2. 왜 사용해야 하는가?

1) 컴파일 시간 단축
스크립트 변경이 일어난 어셈블리만 부분적으로 재컴파일되기 때문에 전체 프로젝트의 빌드 시간이 크게 줄어든다.

2) 코드 모듈화
기능 단위로 코드의 경계를 나눌 수 있어, 의존성과 책임을 명확히 분리할 수 있다. 이는 테스트 작성, 재사용, 유지보수 측면에서 매우 유리하다.

3) 순환 참조 방지
어셈블리 간 참조 방향은 단방향만 허용되므로, 암묵적인 순환 참조를 방지하고 의존성 구조를 명확히 파악할 수 있다.

4) 플랫폼 별 분기 처리에 유리
특정 어셈블리에만 플랫폼 전용 코드를 포함시킬 수 있어, 관리가 수월해진다.

---

3. 사용 방법

1) Assembly Definition 파일 생성
Unity 에디터에서 특정 폴더를 우클릭 → Create > Assembly Definition 선택 후 이름을 지정하면 .asmdef 파일이 생성된다. 이 파일이 위치한 폴더 이하의 스크립트는 이제 해당 어셈블리에 속하게 된다.

2) 의존성 설정
.asmdef 파일의 인스펙터에서 Assembly Definition References에 참조할 다른 asmdef를 추가해야 한다. 참조 설정이 없으면 해당 어셈블리 내에서 다른 어셈블리의 클래스를 사용할 수 없다.

3) 테스트 어셈블리 정의
테스트용 asmdef 파일은 .Tests.asmdef와 같은 형태로 생성할 수 있으며, Test Assemblies 옵션을 활성화해야 한다. 이는 Unity Test Framework와 연동된다.

---

4. 주의할 점

• Editor 전용 코드는 분리 필요
  에디터 전용 코드는 별도의 Editor 폴더에 두고, 해당 폴더에도 별도의 .asmdef 파일을 만들어야 한다. 그리고 이 파일에는 Include Platforms에서 Editor만 체크해야 한다.
• 의존성 역전 금지
  A가 B를 참조하는 경우, B는 A를 참조할 수 없다. 의존성이 꼬이지 않도록 설계가 중요하다.
• UnityEngine, UnityEditor 명시적 참조 필요
  기본 어셈블리 외부에서 UnityEngine 등을 사용할 경우, 해당 어셈블리를 직접 참조 리스트에 추가해야 한다.
• 기존 스크립트와의 혼용 문제
  asmdef가 적용되지 않은 스크립트는 Assembly-CSharp.dll에 속하므로, 상호 참조 시 의존 방향에 주의해야 한다.

---

결론

Assembly Definition은 단순한 컴파일 최적화 기능을 넘어, 프로젝트 아키텍처의 기초를 설계할 수 있게 하는 도구이다. 작은 프로젝트에서는 불필요할 수 있지만, 규모가 커질수록 반드시 도입해야 할 기능이며, 특히 패키지화, 팀 협업, 테스트 작성이 필요한 경우 그 중요성은 더욱 커진다. Unity 개발에 있어 설계 단계부터 asmdef를 고려하는 습관은, 장기적으로 더 안정적이고 유지보수 가능한 코드를 만드는 데 기여할 것이다.