Quick Reference

• 기준 버전은 Unity 6.5 (6000.5)입니다. .asmdef 하나는 자신이 있는 폴더와 하위 폴더의 스크립트를 한 C# 어셈블리로 컴파일합니다. 하위 폴더에 다른 .asmdef가 있으면 그 경계에서 분리됩니다.
• 처음에는 Game.Runtime -> Game.Editor, Game.Runtime -> Game.Tests처럼 역할과 참조 방향이 읽히는 세 어셈블리면 충분합니다. Editor나 Tests가 Runtime을 참조할 수 있어도 Runtime이 역참조하면 빌드와 컴파일 경계가 무너집니다.
• 참조는 필요한 어셈블리만 명시하고, 플랫폼은 기본값인 모든 플랫폼에서 시작합니다. Editor 전용, 테스트 전용, 특정 SDK 전용일 때만 제한합니다.

Game.Runtime.asmdef      게임 실행 코드
Game.Editor.asmdef       UnityEditor 도구, Game.Runtime 참조
Game.Tests.asmdef        NUnit 테스트, Game.Runtime 참조

Inspector 설정

• Name은 만들어질 어셈블리 이름입니다. namespace가 아니므로 Game.Runtime처럼 코드 역할을 드러내는 이름을 씁니다. 이름을 바꾸면 다른 asmdef의 name 기반 reference가 끊길 수 있으므로, 생성 직후의 규칙 변경이 아니라면 GUID reference를 확인한 뒤 바꿉니다.
• Root Namespace는 새 스크립트 생성 때 제안할 namespace입니다. 컴파일 경계나 기존 클래스의 namespace를 바꾸지 않습니다. 폴더 구조와 namespace를 맞추고 싶을 때만 설정합니다.
• Assembly Definition References에는 이 코드가 직접 써야 하는 프로젝트 어셈블리만 넣습니다. 참조를 추가하면 그 대상의 public type을 사용할 수 있고, 대상 변경 시 이 어셈블리도 재컴파일될 수 있습니다. 순환 참조는 허용되지 않습니다.
• Auto Referenced의 기본값은 켜짐입니다. 끄면 미리 정의된 Unity 어셈블리와 다른 asmdef가 이 어셈블리를 자동으로 참조하지 않으므로, 필요한 소비자가 직접 reference를 추가해야 합니다. 독립 플러그인이나 의도적으로 고립한 모듈에는 유용하지만, 기존 Assembly-CSharp 코드에서 type을 못 찾는 원인이 되기도 합니다.
• Override References의 기본값은 꺼짐입니다. 켜면 기본 precompiled plugin 참조 집합 대신 아래의 Assembly References 목록만 사용합니다. 특정 DLL만 허용해 의존성을 좁힐 때 쓰며, 필요한 DLL을 빼면 type or namespace could not be found 컴파일 오류가 납니다.
• No Engine References의 기본값은 꺼짐입니다. 켜면 UnityEngine과 UnityEditor 기본 참조를 넣지 않습니다. 순수 C# 규칙 라이브러리를 만들 때만 쓰며, MonoBehaviour, Vector3, Debug를 쓰는 즉시 컴파일할 수 없습니다.
• Allow 'unsafe' Code의 기본값은 꺼짐입니다. 포인터·unsafe 블록이 실제로 필요한 저수준 코드에만 켭니다. 일반 게임 코드에 켜도 성능이 자동으로 좋아지지 않으며, 지원 플랫폼과 코드 검토 범위만 넓어집니다.
• Include Platforms / Exclude Platforms는 어느 build target에서 컴파일할지 정합니다. 둘 다 비워 두면 모든 플랫폼입니다. Editor 도구는 Include Platforms에서 Editor만 선택합니다. Runtime 코드를 Editor만으로 제한하면 player build에서 그 type 자체가 없어집니다.
• Define Constraints는 지정 symbol이 있을 때만 이 어셈블리를 컴파일합니다. SDK 선택 기능처럼 코드 존재 자체를 조건부로 만들 때 씁니다. 일반 #if를 대신하는 기능이 아니며, 조건이 거짓이면 참조한 어셈블리가 type을 찾지 못할 수 있습니다.
• Test Assemblies는 Test Framework와 nunit.framework를 참조하도록 만드는 설정입니다. 테스트 asmdef에만 켭니다. Runtime asmdef에 켜면 테스트 dependency가 제품 코드 경계로 들어옵니다.

참조와 테스트 연결

{
  "name": "Game.Tests",
  "references": ["GUID:0123456789abcdef0123456789abcdef"],
  "includePlatforms": ["Editor"],
  "optionalUnityReferences": ["TestAssemblies"]
}

• Inspector가 만드는 .asmdef JSON입니다. references의 GUID 형식은 대상 asmdef의 이름 변경에도 참조를 유지하기 좋습니다. JSON을 직접 고칠 수는 있지만 Inspector가 쓸 수 있는 값만 넣고, 수정 뒤 Unity가 재임포트한 오류를 먼저 확인합니다.
• .asmref는 새 어셈블리를 만들지 않고 다른 폴더를 기존 asmdef에 포함할 때 씁니다. shared source 폴더를 Runtime 어셈블리에 넣는 용도에는 맞지만, 의존성 문제를 숨기기 위한 우회 수단으로 쓰면 소유 폴더가 불명확해집니다.
• 테스트는 Game.Tests에서 Game.Runtime의 public API만 사용하게 두는 편이 좋습니다. internal 접근이 꼭 필요하면 InternalsVisibleTo를 명시적으로 추가하고, 테스트 편의를 이유로 제품 API를 public으로 넓히지 않습니다. EditMode와 PlayMode runner 선택은 Unity Test Framework 기본에서 이어서 확인합니다.

자주 틀리는 부분