비주얼 로거(Visual Logger) 는 게임플레이 상태의 시각적 표현을 생성 및 기록하고 에디터에서 이 데이터를 리뷰하는 기능을 제공하는 강력한 디버깅 툴입니다. 개발자가 디버그 출력을 플레이 세션 도중에 실시간으로 확인하거나 세션 종료 후 에디터에서 검토할 수 있어서, 사용자 보고나 게임 영상만으로는 트래킹하기 어려운 게임플레이 버그를 훨씬 쉽게 해결할 수 있습니다. 향후 리뷰를 위해 정보를 기록하는 기능은 드물거나 재현하기 어려운 버그를 수정할 때 특히 중요합니다. 예를 들어 한 프레임마다 변경되는 게임 상태 변수에 의해 발생하는 예상치 못한 AI 행동의 데이터가 기록되면, 나중에 버그가 일어난 순간의 프레임을 스크럽하면서 조사할 수 있습니다.
비주얼 로거를 활성화하려면 창(Windows) > 개발자 도구(Developer Tools) > 비주얼 로거(Visual Logger) 메뉴를 사용합니다. 4.27 이전 버전의 언리얼 엔진에서는 콘솔 명령 "VisLog"를 입력합니다. 에디터에 있는 경우 비주얼 로거 뷰포트도 열릴 것입니다.

에픽게임즈 샘플 StrategyGame 세션 중에 비주얼 로그를 사용하는 모습입니다. 보라색 선은 AI의 경로를 나타내며, 빨간색 위치 마커는 타임라인에서 선택된 포인트를 표시합니다.
비주얼 로거 뷰포트
에디터에서 비주얼 로거 뷰포트는 사전 기록된 세션의 비주얼 로거 출력을 리뷰할 수 있게 합니다. 개발자는 이를 통해 버그를 사후에 리뷰할 수 있습니다.

에디터의 비주얼 로거 뷰포트입니다.
이 뷰포트에는 시각화 데이터를 로깅한 모든 액터의 목록, 액터 목록에서 선택된 액터의 상태에 대한 상세한 스냅샷, 디버그 메시지 출력을 표시하는 텍스트 창, 기록된 데이터를 스크럽할 수 있는 타임 바가 있습니다.
액터 목록
다음 이미지에서 하이라이트된 영역은 기록된 세션 도중 비주얼 로거에 정보를 기록한 액터의 목록을 보여줍니다. 사용자가 특정 액터의 로그 정보를 빠르게 찾도록 도와주는 검색 바도 있습니다.

액터 목록과 검색 바입니다.
액터 스냅샷 뷰
액터가 UE_VLOG
매크로로 수집하는 모든 데이터는 다음 이미지의 하이라이트된 영역에 나타납니다. 비주얼 로거는 타임라인 스크러버에 표시된 시간에 액터 목록에서 선택된 액터로부터 발생하는 데이터를 표시합니다. 비주얼 로거가 스냅샷의 일부로서 캡처하는 데이터는 게임 코드에서 카테고리별로 분류하고 커스터마이징할 수 있으며, 이 카테고리는 펼치거나 접을 수 있습니다.
같은 프레임, 같은 액터에서 다수의 비주얼 로깅을 호출하면 이전에 캡처된 데이터가 덮어씌워집니다.

커스텀 카테고리가 펼쳐진 액터 스냅샷 영역입니다.
텍스트 창
비주얼 로거의 텍스트 창은 현재 프레임의 로그 메시지를 카테고리별로 나눠서 표시합니다. 같은 카테고리, 같은 프레임에서 기록된 다수의 로그 메시지는 목록으로 표시됩니다.

디버그 메시지가 나타나는 텍스트 창 영역입니다.
타임라인
타임라인 뷰에는 로거를 선택한 시점으로 빨리감거나 되감는 바가 있습니다. 아래 이미지에서 스크러버는 23.53초에 있고, 액터 목록에서는 "StrategyAIController_1"이 선택되어 있습니다. 타임 바를 스크럽하여 기록된 로그 데이터의 여러 시점에 선택된 액터의 상태 및 텍스트 창을 볼 수 있습니다.

타임라인 영역입니다.
비주얼 로거 지원 추가
비주얼 로거에 추가할 수 있는 데이터 유형은 세 가지입니다.
데이터 유형 | 출력 설명 |
---|---|
액터 스냅샷 | 액터 스냅샷 영역에 나타나며, 액터가 존재하는 동안 프레임마다 1회 업데이트됩니다. |
로그 메시지 | 비주얼 로거로 로깅하는 모든 텍스트가 텍스트 창에 표시됩니다. 텍스트는 단일 프레임 기반으로 표시됩니다. |
디버그 셰이프 | 게임 월드에 다양한 셰이프를 그릴 수 있습니다. 이 셰이프는 여러 프레임 동안 유지될 수 있으며, 크기와 색상 등 다수의 조정 가능한 파라미터를 갖습니다. |
액터 스냅샷 찍기
액터 스냅샷 뷰에 데이터를 추가하려면 먼저 IVisualLoggerDebugSnapshotInterface
인터페이스 함수를 다음과 같이 구현해야 합니다.
class MYPROJECT_API AMyActor : public AActor, public IVisualLoggerDebugSnapshotInterface
이 인터페이스에는 기본적으로 아무 기능도 하지 않는 GrabDebugSnapshot
함수만 있습니다. 이 함수를 오버라이드하여 비주얼 로거에 정보를 입력할 수 있습니다. GrabDebugSnapshot
은 비주얼 로거가 활성화된 빌드에서만 실행되므로 관련된 모든 코드에서 ENABLE_VISUAL_LOG
매크로를 확인하는 것이 좋습니다. 예를 들어 액터 클래스에서의 함수 선언은 다음과 같은 코드 블록을 포함할 수 있습니다.
#if ENABLE_VISUAL_LOG
//~ IVisualLoggerDebugSnapshotInterface 인터페이스 시작
// 이 액터에 대한 정보를 비주얼 로거에 추가합니다.
virtual void GrabDebugSnapshot(FVisualLogEntry* Snapshot) const override;
//~ IVisualLoggerDebugSnapshotInterface 인터페이스 끝
#endif
다음 샘플 코드는 커스터마이징된 버전의 일인칭 슈팅 템플릿 캐릭터 클래스 AGDCCharacter
에 비주얼 로깅을 추가한 GDC 데모 중 일부입니다. 이 코드는 "GDC Sample" 카테고리에 단일 엔트리를 추가합니다. 이 엔트리는 "Projectile Class"로 라벨 지정되며, 캐릭터가 발사 시 스폰하는 투사체 유형을 포함합니다.
#if ENABLE_VISUAL_LOG
void AGDCCharacter::GrabDebugSnapshot(FVisualLogEntry* Snapshot) const
{
Super::GrabDebugSnapshot(Snapshot);
const int32 CatIndex = Snapshot->Status.AddZeroed();
FVisualLogStatusCategory& PlaceableCategory = Snapshot->Status[CatIndex];
PlaceableCategory.Category = TEXT("GDC Sample");
PlaceableCategory.Add(TEXT("Projectile Class"), ProjectileClass != nullptr ? ProjectileClass->GetName() : TEXT("None"));
}
#endif
이 함수는 비주얼 로거에 자동으로 첫 호출을 실행합니다. 액터 스냅샷 뷰에서 보고자 하는 정보를 이 함수에 추가하세요.

AGDCCharacter 의 액터 스냅샷이 있는 비주얼 로거입니다.
텍스트 로깅
UE_VLOG
매크로로 텍스트 창에 로깅할 수 있습니다. 텍스트 창은 프레임별로 정보를 표시하므로, 기록된 데이터를 스크럽할 때는 현재 프레임에서 로깅된 텍스트만 표시됩니다. 텍스트는 어디서든 로깅할 수 있으며 UE_VLOG
매크로는 비주얼 로깅 시스템을 지원하지 않는 빌드의 컴파일에서 스스로 깔끔하게 제거되므로, ENABLE_VISUAL_LOG
매크로를 체크하지 않고 사용하는 것이 안전합니다. 이 매크로는 텍스트와 연결된 액터, 로그 카테고리, 상세도 레벨(디스플레이 필터링에 사용됨), 텍스트 자체 등의 파라미터를 받습니다.
다음 샘플 코드에서는 커스터마이징된 캐릭터가 투사체를 발사한 후 UE_VLOG
를 사용하여 정보를 로깅합니다.
void AGDCCharacter::OnFire()
{
// 투사체 발사를 시도합니다.
if (ProjectileClass != NULL)
{
// 에임 회전을 수집합니다.
const FRotator SpawnRotation = GetControlRotation();
// MuzzleOffset은 카메라 스페이스에 있으므로 캐릭터 위치에서 오프셋하기 전에 월드 스페이스로 변환하여 최종 총구 위치를 찾습니다.
const FVector SpawnLocation = GetActorLocation() + SpawnRotation.RotateVector(GunOffset);
UWorld* const World = GetWorld();
if (World != NULL)
{
// 총구 위치에서 월드에 투사체를 스폰합니다.
World->SpawnActor<AGDCProjectile>(ProjectileClass, SpawnLocation, SpawnRotation);
// 비주얼 로거로 이 이벤트를 로깅합니다.
UE_VLOG(this, LogFPChar, Verbose, TEXT("Fired projectile (%s) from location (%s) with rotation (%s)"),
*ProjectileClass->GetName(),
*SpawnLocation.ToString(),
*SpawnRotation.ToString());
}
}
// ...
}

AGDCCharacter 의 디버그 텍스트를 표시하는 비주얼 로거입니다.
복제 메시지를 표준 로그로 전송하려면, 같은 데이터로 UE_LOG
다음에 UE_VLOG
를 호출하는 대신 UE_VLOG_UELOG
매크로를 사용합니다.
디버그 셰이프 그리기
게임 월드에서 셰이프 정보를 로깅하는 기능은 현재 상황을 시각화하도록 도와주므로 대단히 유용합니다. 다음 이미지는 비주얼 로거가 지원하는 다양한 셰이프 타입을 보여줍니다.

경로 정보, 원기둥, 원뿔, 캡슐, 박스 셰이프.
로깅 셰이프를 지원하는 매크로는 다음과 같습니다. 각 매크로는 셰이프를 소유하는 액터, 로그 카테고리, 상세도 레벨, 셰이프에 따라 다른 여러 추가적인 셰이프 정의 파라미터와 셰이프에 수반되는 텍스트를 필요로 합니다. 다음 표에는 사용 가능한 셰이프와 각 셰이프에서 필요로 하는 추가 파라미터의 정보가 있습니다.
셰이프 | 설명 | 추가 파라미터 |
---|---|---|
UE_VLOG_SEGMENT |
1픽셀 굵기의 선 세그먼트 |
|
UE_VLOG_SEGMENT_THICK |
다양한 굵기의 선 세그먼트 |
|
UE_VLOG_LOCATION |
스피어 |
|
UE_VLOG_BOX |
축 정렬된 박스 |
|
UE_VLOG_OBOX |
회전된 박스 |
|
UE_VLOG_CONE |
원뿔 |
|
UE_VLOG_CYLINDER |
원기둥 |
|
UE_VLOG_CAPSULE |
캡슐 |
|
UE_VLOG_MESH |
3D 메시 |
|
UE_VLOG_CONVEXPOLY |
2D 컨벡스 헐 폴리곤 |
|
UE_VLOG_ARROW |
화살표가 있는 선 세그먼트 |
|