Quick Reference

UXML은 구조, USS는 layout·style, C#은 event·data를 연결하고 UIDocument와 PanelSettings로 panel·입력·scale 경계를 정합니다.

• 기준 버전은 Unity 6.5 (6000.5)입니다. UXML은 visual tree 구조, USS는 layout·style, C#은 query·event·runtime data 연결을 맡습니다. UIDocument는 씬과 UXML의 연결점이고 PanelSettings가 panel의 렌더·입력·scale 정책을 가집니다.
• runtime UI에서도 UI Toolkit을 쓸 수 있습니다. 다만 새 PanelSettings를 자동 탐색하게 두지 말고, 화면이 공유할 panel과 sorting/focus 경계를 Inspector에서 명시합니다.
• data binding은 runtime에 지원되지만 모든 C# 객체가 자동으로 화면에 반영되는 것은 아닙니다. binding source와 변경 알림 contract를 정하거나, controller에서 명시적으로 값을 갱신합니다.

Inspector 설정

• UIDocument > Panel Settings는 그 문서의 panel, scale, input, sort 문맥을 정합니다. 비워두면 프로젝트에서 찾은 Panel Settings를 사용할 수 있어 asset 이동 후 다른 panel에 붙는 사고가 생길 수 있습니다.
• Source Asset은 UXML VisualTreeAsset입니다. OnEnable에서 visual tree가 생성되므로, root query와 event 등록은 Awake보다 OnEnable 이후에 둡니다.
• Sort Order는 같은 level의 UIDocument rendering 순서입니다. 같은 PanelSettings를 공유하는 문서는 focus navigation context도 공유합니다. popup과 HUD를 별 panel로 나누면 focus 이동과 입력 차단 정책도 따로 설계해야 합니다.
• Panel Settings의 Theme Style Sheet, Text Settings, Target Display, Sort Order, Scale Mode는 panel 전체에 적용됩니다. Target Texture는 3D geometry에 표시하는 경로가 될 수 있지만, 일반적인 World Space Canvas와 동일한 workflow로 가정하지 말고 input raycast·render texture mapping을 따로 검증합니다.

스크립트 연결

using UnityEngine;
using UnityEngine.UIElements;

public sealed class MainMenuDocument : MonoBehaviour
{
    [SerializeField] private UIDocument document;
    private Button startButton;

    private void OnEnable()
    {
        startButton = document.rootVisualElement.Q<Button>("start-button");
        startButton.clicked += StartGame;
    }

    private void OnDisable()
    {
        startButton.clicked -= StartGame;
    }

    private void StartGame() { }
}

• rootVisualElement.Q<T>(name)은 UXML의 name으로 element를 찾습니다. 없는 element면 null이므로 UXML 이름 변경은 code contract 변경입니다.
• clicked와 RegisterCallback<ClickEvent>은 Button event 연결 방법입니다. clicked는 간단한 click, callback은 event propagation·pointer details가 필요할 때 사용합니다.
• 재사용할 화면은 rootVisualElement.style.display = DisplayStyle.None으로 숨길 수 있습니다. 이렇게 숨겨도 element tree와 등록한 callback은 남으므로, 표시/숨김과 수명 종료를 구분합니다.

자주 틀리는 부분