Development & Debug Tools for UMG/Slate

언리얼 엔진은 UMG 및 Slate UI를 개발할 때 사용할 수 있는 다양한 개발 및 디버그 도구를 제공합니다.
이 도구들은 에디터뿐만 아니라 패키징된 개발 빌드(콘솔 포함)에서도 활용할 수 있어 UI 제작과 디버깅에 큰 도움이 됩니다.

Debug Console Commands

콘솔 슬레이트 디버거 공식 문서
(External Links Page에도 링크되어 있습니다.)

• Slate Debugger 관련 콘솔 명령어는 Slate Console Debugger Console Commands 섹션을 참고하세요.
• Slate.HitTestGridDebugging [0/1]: UMG/Slate 포커싱 히트 테스트 그리드 표시 플래그입니다.
• SlateDebugger.Invalidate.[Disable/Enable]: 인밸리데이션 디버거 시각화 도구를 활성화/비활성화합니다.
• Safe Zone 관련 명령어:
  • r.DebugSafeZone.TitleRatio 0.96: 기본값은 1.0. Safe Zone이 정의되지 않은 플랫폼에서 FDisplayMetrics::GetDisplayMetrics가 반환하는 타이틀 세이프존 비율(0~1).
  • r.DebugActionZone.ActionRatio 0.96: 기본값은 1.0. Safe Zone이 정의되지 않은 플랫폼에서 액션 세이프존 비율(0~1).
  • r.DebugSafeZone.Mode [0~2]
    • 0: 세이프존 오버레이를 표시하지 않음
    • 1: 타이틀 세이프존 오버레이 표시
    • 2: 액션 세이프존 오버레이 표시
• Slate.ThrottleWhenMouseIsMoving [0/1]: 기본값은 false. 마우스 커서 이동에 따라 UI 반응성을 높일지 여부.
  • true: 마우스 움직임에 따라 슬레이트 틱을 스로틀링(최적화)합니다.
• Slate.TargetFrameRateForResponsiveness [정수]: 기본값은 35. 에디터가 "반응성 있음"으로 간주되는 최소 평균 프레임레이트(부드러운 UI 경험을 위한 기준).
• Slate.AllowSlateToSleep [0/1]: 슬레이트가 활성 타이머가 없고 사용자가 유휴 상태일 때 슬립 모드로 진입할지 여부.
• Slate.SleepBufferPostInput [실수]: 기본값은 0.0. 사용자 입력 이후 슬레이트가 슬립 모드로 진입하기까지 대기할 시간(초).
• Slate.RequireFocusForGamepadInput [0/1]: 기본값은 false. 애플리케이션이 활성 상태가 아닐 때 게임패드 입력을 무시할지 여부.
• Slate.Transform.FullscreenMouseInput [0/1]: 기본값은 true. 전체화면 해상도에서 뷰포트 스트레칭을 보정해 마우스 입력을 변환할지 여부.
• Slate.EnableTooltips [0/1]: 플랫폼에 따라 기본값이 다름. 툴팁 UI 표시를 허용할지 여부.
• Slate.TriggerInvalidate: 모든 위젯을 전역적으로 인밸리데이트(무효화)합니다. Shipping 빌드에서는 동작하지 않습니다.
• Slate.ShowTextDebugging [0/1]: 텍스트 렌더링 디버그 페인팅을 표시합니다. Shipping 빌드에서는 동작하지 않습니다.

Widget Reflector

Widget Reflector 공식 문서
(External Links Page에도 링크되어 있습니다.)

Widget Reflector를 열려면 에디터 메뉴에서 Tools/Debug/Widget Reflector로 이동하거나, 소스 버전의 언리얼 엔진을 사용하는 경우 별도의 애플리케이션으로 빌드할 수 있습니다.

Widget Reflector는 UI 최적화 및 디버깅을 위한 도구로, 다음과 같은 기능을 제공합니다:

• 위젯 계층 구조: 부모-자식 관계를 트리 형태로 시각화하며, 아래 속성들을 확인할 수 있습니다.
  • 위젯 이름
  • 전경 가시성(FG Visibility)
  • 포커스 상태
  • 클리핑
  • 소스: 해당 위젯의 소스 코드 위치(빠른 접근 가능)
  • 주소: Slate가 위젯 계층 및 트리 계산에 사용하는 내부 경로
• 위젯 상세 정보: 위젯의 가시성, 포커스 등 Slate 위젯이 노출하는 다양한 속성 확인
• 위젯 이벤트:
  • 입력(Input)
  • 포커스(Focus)
  • 내비게이션(Navigation)
  • 경고(Warning)
  • 마우스 캡처(Mouse Capture)
• 위젯 내비게이션 및 히트 테스트 그리드 시각화
• 인밸리데이션(Invalidation) 상태 확인
• 위젯 업데이트 및 페인트(Paint) 정보 확인
• 클리핑(Clipping), 컬링(Culling), 캐싱(Caching) 등 Slate 렌더링 관련 정보 확인

콘솔이나 모바일 등 외부 디바이스에서 디버깅할 때는 엔진의 "Remote Session" 플러그인(구 Slate Remote)을 사용해 디바이스에 연결하면, Widget Reflector로 실시간 UMG/Slate 디버깅이 가능합니다.

콘솔이나 모바일 등 외부 디바이스에서 디버깅할 때는 엔진의 "Remote Session" 플러그인(구 Slate Remote)을 사용해 디바이스에 연결하면, Widget Reflector로 실시간 UMG/Slate 디버깅이 가능합니다.

Slate Console Debugger

Slate Console Debugger는 Slate의 다양한 부분을 디버깅할 수 있도록 제공되는 콘솔 명령어 모음입니다.
각 콘솔 명령어는 SlateDebugger.로 시작하며, 옵션을 활성화하면 해당 디버그 정보가 출력 로그에 표시됩니다.

좋은 점은, 위젯 리플렉터(Widget Reflector)에서 이러한 플래그를 직접 켜고 끌 수 있으므로, 일일이 콘솔 명령어를 입력하지 않아도 된다는 것입니다.

아래는 각 Slate Debugger 콘솔 명령어의 목록입니다:

• Slate Trace (SlateTrace.cpp)

  • SlateDebugger.bCaptureRootInvalidationCallstacks [0/1]: 위젯이 인밸리데이션의 루트 원인일 때, Slate Insights(언리얼 Insights의 디버깅 도구)에서 콜스택을 캡처합니다.

• Events (ConsoleSlateDebugger.cpp)

  • SlateDebugger.Event.Start 또는 SlateDebugger.Start: 이벤트 디버거 시작
  • SlateDebugger.Event.Stop 또는 SlateDebugger.Stop: 이벤트 디버거 중지
  • SlateDebugger.Event.LogWarning: 경고 이벤트 로그
  • SlateDebugger.Event.LogInputEvent: 입력 이벤트 로그
  • SlateDebugger.Event.LogFocusEvent: 포커스 이벤트 로그
  • SlateDebugger.Event.LogAttemptNavigationEvent: 내비게이션 시도 이벤트 로그
  • SlateDebugger.Event.LogExecuteNavigationEvent: 내비게이션 실행 이벤트 로그
  • SlateDebugger.Event.LogCaptureStateChangeEvent: 입력 캡처 상태 변경 이벤트 로그
  • SlateDebugger.Event.LogCursorChangeEvent: 커서 변경 이벤트 로그
  • SlateDebugger.Event.CaptureStack: 이벤트 발생 시 콜스택 캡처 및 로그 토글
  • SlateDebugger.Event.InputRoutingModeEnabled: 입력 이벤트가 어떤 경로로 전달됐는지 로그 토글
  • SlateDebugger.Event.SetInputFilter [Filter]: 특정 입력 필터 토글
    • 필터 종류:
      • MouseMove, MouseEnter, MouseLeave, PreviewMouseButtonDown, MouseButtonDown, MouseButtonUp, MouseButtonDoubleClick, MouseWheel
      • TouchStart, TouchEnd, TouchForceChanged, TouchFirstMove, TouchMoved
      • DragDetected, DragEnter, DragLeave, DragOver, DragDrop, DropMessage
      • PreviewKeyDown, KeyDown, KeyUp, KeyChar, AnalogInput, TouchGesture, MotionDetected
  • SlateDebugger.Event.DisableAllInputFilters: 모든 입력 필터 비활성화
  • SlateDebugger.Event.EnableAllInputFilters: 모든 입력 필터 활성화
  • SlateDebugger.Event.SetFocusFilter [Filter]: 특정 포커스 필터 토글
    • 필터 종류: FocusChanging, FocusLost, FocusReceived
  • SlateDebugger.Event.ClearFocusFilters: 모든 포커스 필터 비활성화
  • SlateDebugger.Event.EnableAllFocusFilters: 모든 포커스 필터 활성화

• Breaks (ConsoleSlateDebuggerBreak.cpp)
  디버거가 에디터에 연결되어 있을 때만 동작하며, 브레이크포인트로 활용할 수 있습니다.

  • SlateDebugger.Break.OnWidgetInvalidation Reason=[Reason][WidgetPtr][WidgetId]: 입력한 위젯이 인밸리데이트될 때 중단
    • Reason 종류: Layout, Paint, Volatility, ChildOrder, RenderTransform, Visibility, AttributeRegistration, Prepass, PaintAndVolatility, LayoutAndVolatility
  • SlateDebugger.Break.OnWidgetBeginPaint [WidgetPtr][WidgetId]: 위젯 페인트 시작 전 중단
  • SlateDebugger.Break.OnWidgetEndPaint [WidgetPtr][WidgetId]: 위젯 페인트 직후 중단
  • SlateDebugger.Break.RemoveAll: 모든 브레이크 요청 제거

• Paint (ConsoleSlateDebuggerPaint.cpp)

  • SlateDebugger.Paint.Start: 페인트된 위젯 디버그 도구 시작(이 프레임에 페인트된 위젯 표시)
  • SlateDebugger.Paint.Stop: 페인트 디버그 도구 중지
  • SlateDebugger.Paint.Enable: 페인트 디버그 도구 토글
  • SlateDebugger.Paint.LogOnce: 마지막 업데이트에서 페인트된 모든 위젯 이름 로그
  • SlateDebugger.Paint.MaxNumberOfWidgetDisplayedInList [MaxNumberOfWidgetsInList]: 표시할 위젯 이름 최대 개수 설정
  • SlateDebugger.Paint.ToggleWidgetNameList: 페인트된 위젯 이름 표시 토글
  • SlateDebugger.Paint.LogWarningIfWidgetIsPaintedMoreThanOnce: 한 프레임에 여러 번 페인트된 위젯 경고 로그 토글
  • SlateDebugger.Paint.OnlyGameWindow: 게임 윈도우의 위젯만 디버깅

• Update (ConsoleSlateDebuggerUpdate.cpp)

  • SlateDebugger.Update.Start: 위젯 업데이트 디버그 도구 시작
  • SlateDebugger.Update.Stop: 업데이트 디버그 도구 중지
  • SlateDebugger.Update.Enable: 업데이트 디버그 도구 토글
  • SlateDebugger.Update.ToggleLegend: 컬러 범례 표시 토글
  • SlateDebugger.Update.ToggleWidgetNameList: 업데이트된 위젯 이름 표시 토글
  • SlateDebugger.Update.ToggleUpdateFromPaint: 업데이트 플래그가 없지만 다른 위젯의 영향으로 업데이트된 위젯도 표시
  • SlateDebugger.Update.SetWidgetUpdateFlagsFilter: 특정 업데이트 플래그 필터 토글
    • 플래그 종류(WidgetUpdateFlags.h): None, Tick, ActiveTimer, Repaint, VolatilePaint, Any
  • SlateDebugger.Update.SetInvalidationRootIdFilter: 인밸리데이션 루트에 속한 위젯만 표시 토글
  • SlateDebugger.Update.OnlyGameWindow: 게임 윈도우 디버그 정보만 표시

• Invalidation (ConsoleSlateDebuggerInvalidate.cpp)

  • SlateDebugger.InvalidationRoot.Start: 인밸리데이션 위젯 디버그 도구 시작(인밸리데이트된 위젯 표시)
  • SlateDebugger.InvalidationRoot.Stop: 인밸리데이션 디버그 도구 중지
  • SlateDebugger.InvalidationRoot.Enabled: 인밸리데이션 디버그 도구 토글
  • SlateDebugger.InvalidationRoot.bShowLegend: 컬러 범례 표시 토글
  • SlateDebugger.InvalidationRoot.bShowWidgetList: 인밸리데이트된 위젯 이름 표시 토글
  • SlateDebugger.InvalidationRoot.bLogInvalidatedWidget: 인밸리데이트된 위젯 콘솔 로그 토글
  • SlateDebugger.InvalidationRoot.ThresholdPerformanceMS: 성능 임계값(ms) 설정(이 값보다 느릴 때만 표시/로그)
  • SlateDebugger.InvalidationRoot.bUsePerformanceThreshold: 임계값 초과 시에만 표시/로그
  • SlateDebugger.InvalidationRoot.SetInvalidateRootReasonFilter: 특정 인밸리데이션 루트 사유 필터 토글
    • 필터 종류(SlateDebugging.h): None, ChildOrder, Root, ScreenPosition

• Invalidation Root (ConsoleSlateDebuggerInvalidationRoot.cpp)

  • SlateDebugger.InvalidationRoot.Start: 인밸리데이션 루트 위젯 디버그 도구 시작(슬로우/패스트 패스 사용 시점 표시)
  • SlateDebugger.InvalidationRoot.Stop: 인밸리데이션 루트 디버그 도구 중지
  • SlateDebugger.InvalidationRoot.Enable: 인밸리데이션 루트 디버그 도구 토글
  • SlateDebugger.InvalidationRoot.ToggleLegend: 컬러 범례 표시 토글
  • SlateDebugger.InvalidationRoot.ToggleWidgetNameList: 인밸리데이션 루트 이름 표시 토글