[Unity] UI Toolkit 기본 사용법

■ UI Toolkit

[UI Toolkit]

UI Toolkit은 Unity 2022.2 이후 유니티의 기존 UGUI(Canvas 기반 UI)를 대체할 수 있도록 개발된 새로운 공식 UI 시스템이다.

 

기존 UGUI는 GameObject 기반으로 동작하는 UI 시스템으로 드래그 앤 드롭을 통한 직관적인 UI 제작이 가능하다. 또한 하이어라키 구조와 Canvas의 SortOrder를 이용해 UI의 렌더링 순서를 제어할 수 있다.

• UGUI는 편리하고 직관적인 반면에 아래와 같은 뚜렷한 단점도 존재한다.

구분	단점
GameObject 기반	UGUI의 모든 UI요소는 GameObject + Component 로 구성된다.  → 따라서 많은 UI요소가 있으면 UpdateLoop, Transform 갱신 등 CPU 오버헤드와메모리 사용량이 커진다.
Canvas 전체 리빌드	Canvas내 어느 한 UI요소라도 변경되면, Unity는 Canvas 전체를 다시 빌드(Rebuild) 해야 한다.
실시간 갱신 비효율	위와 같은 이유로 인하여, 실시간으로 수치나 상태가 바뀌는 UI(경험치, 체력바 등)는 Canvas 리빌드와 Layout 계산이 지속적으로 발생한다

[Web 개발 방식을 적용]

UI Toolkit은 기존 UGUI의 성능 및 유지보수 문제를 해결하기 위해, 웹 개발에 사용되는 스크립트(HTML, CSS, Java)를 Unity 환경에 도입하여 UI를 구성할 수 있도록 했다.

• .UXML(HTML) : 기존 웹 개발의 프런트 레이아웃과 비슷한 구조를 가지고 있다. 유니티에서 UI의 레이아웃을 담당한다.
• .USS(CSS) : UI의 스타일을 결정.
• .cs : 인터페이스의 컨트롤 및 이벤트는 C# 스크립트에서 정의.

웹 개발과 상당히 흡사한 방식을 사용하기 때문에, 웹 개발 경험이 있다면 쉽게 인터페이스를 제작할 수 있고, 게임 내 UI뿐만 아니라 에디터 윈도우도 직접 제작할 수 있다.

 

■ UI Toolkit 사용하기

인게임 UI는 아직 UGUI를 사용하는 경우가 많으므로, UI Toolkit을 사용하여 커스텀 에디터를 만들어보자.

[Editor Window 생성]

Project → Create → UI Toolkit → Editor Window를 클릭하고 이름을 입력하면 자동으로 3개의 파일(.cs, .uss, .uxml)파일이 만들어진다.

 

▶ UI Builder

[UI Builder]

만들어진 .uxml 파일을 클릭하면 위와 같이 UI를 만들 수 있는 UI Builder 창이 열리게 된다. UI Builder의 레이아웃과 역할은 다음과 같다.

1. Style sheet : 현재 문서에 연결된 USS 스타일시트 목록을 표시한다.
2. Hierarchy : UXML의 Visual Tree(계층구조)를 표시한다. 드래그 앤 드롭으로 부모/자식 관계를 조정하고 이름 등을 설정할 수 있다.
3. Library : 배치 가능한 UI요소(VisualElement, Lable, Button 등)와 공통 템플릿 제공.
4. Viewport : 편집 중인 UI를 실시간으로 확인한다.
5. Preview : 현재 상태의 UXML, USS 코드 미리 보기(읽기 전용)를 제공한다.
6. Inspector : 선택한 UI요소의 속성을 편집한다. UGUI 컴포넌트가 아닌 웹에서 사용되는 프로퍼티를 Unity에서 사용 가능하도록 재구성.

 

■ VisualElement

VisualElement는 UI Toolkit에서 가장 기본이 되는 구성 요소이다. 모든 UI 요소들은 이 클래스를 상속받아 만들어진다.

[VisualElement 생성]

두 개의 VisualElement를 생성하고 이름을 각각 Main, Sub로 지정해 준 뒤, 인스펙터의 BackGround 탭에서 색상을 조절하면 위와 같이 배경색이 적용된다.

 

VisualElement는 하위 UI 요소를 배치할 영역(Container)을 정의하는 데 사용한다.

[하위 오브젝트 배치]

VisualElement 안에 요소를 배치하면, 그 영역에 맞게 UI 요소들이 배치되는 것을 확인할 수 있다.

위 사진의 빨간색 박스 안의 4개의 버튼은 현재 선택한 VisualElement의 레이아웃 정렬 및 크기 설정 방식을 변경한다.

• 좌측의 버튼부터 아래와 같은 기능을 한다.

[Flex Direction / Align Items ]

[Justify Content / Align self]

현재 Viewport에서 설정된 테마는 기본적으로 Cinemachine Runtime Theme가 적용되어 있다.

하지만 지금은 런타임 UI가 아닌 커스텀 에디터 창이므로, 이 테마를 Editor용 테마로 변경해 주어야 한다.

• Cinemachine Runtime Theme를 사용하면 Viewport에서 보는 모습과 실제 커스텀 에디터는 다르게 보임.

[라이브러리 설정]

UI Builder 좌측 하단 Library 패널의 오른쪽 상단 점(⋯) 메뉴를 클릭하고 Editor Extension Authoring

옵션을 활성화하면, Viewport의 Theme 드롭다운에서 Dark 혹은 Light테마를 선택할 수 있게 된다.

 

■ 코드 작성

UXML로 UI의 레이아웃을 지정해주었으니, C# 코드를 통해 UI에 기능을 부여해야 한다.

public class TestWindow : EditorWindow
{
    [SerializeField] private VisualTreeAsset visualTreeAsset = default;

    [MenuItem("Window/UI Toolkit/TestWindow")]
    public static void ShowWindow()
    {
        var wnd = GetWindow<TestWindow>();
        wnd.titleContent = new GUIContent("TestWindow");
    }

    public void CreateGUI()
    {
        
    }
}

[TestWindow.cs]

기본적으로 생성된 파일에는 위와 같이 작성되어 있다. 만약 처음부터 작성하는 경우라면, 아래와 같은 변수와 함수를 선언해주어야 한다.

 

1. VisualTreeAsset visualTreeAsset : .uxml 파일을 참조하고, 다루기 위한 변수. UXML이 UI구조를 저장한 설계도라면, VisualTreeAsset은 그 설계도를 메모리에서 다루는 리소스 객체이다.

[.uxml 연결]

 

 → 해당 변수를 선언하고 난 뒤, .uxml 파일을 링크해주어야 한다.

2. [MenuItem("경로")] : 상단 메뉴에 “경로”로 입력한 곳에 커스텀 에디터를 띄울 수 있는 버튼을 추가한다.

3. public static void “이름:”() : 버튼이 클릭되면, 해당 함수를 호출하고 EditorWindow를 생성 및 호출한다.

 

▶ CreateGUI()

EditorWindow 클래스에서 UI Toolkit을 사용할 때 자동으로 호출되는 함수이다. 이 함수에서 UI 요소에 기능을 추가하거나 새로운 UI요소를 생성할 수 있다.

public void CreateGUI()
{
	var root = rootVisualElement;
	visualTreeAsset.CloneTree(root);
}

rootVisualElement는 현재 창의 최상위 컨테이너이다. 이 안에 모든 UI 요소(버튼, 라벨 등)가 들어간다.

 

CloneTree()는 인스펙터에서 참조한 UXML 파일(visualTreeAsset)을 기반으로 실제 UI 인스턴스를 생성하여 최상위 컨테이너 안에 배치한다.

public void CreateGUI()
{
	var root = rootVisualElement;
	visualTreeAsset.CloneTree(root);
	
	var label = root.Q<Label>("TextInfo");
	var button = root.Q<Button>("TestButton");

	button.clicked += () =>
	{
		Debug.Log(label.text);
	};
}

UI요소를 가져올 땐 Q<T>(”이름”) 혹은 Query<T>(”이름”)을 사용한다.

• Q<T>(”이름”) : 첫 번째로 일치하는 요소 1개를 가져온다.
• Query<T>(”이름”) : 트리 내 모든 일치하는 요소를 검색하며, 결과를 리스트로 사용하려면 .ToList()를 함께 사용한다.

위 코드는 UXML에 정의된 Lable과 Button 요소를 가져온 뒤, 버튼을 클릭하면 해당 라벨의 텍스트를 콘솔에 출력한다.