3-3. Log 출력하기

게임 개발 중 로직이 기대대로 동작하지 않을 때 가장 먼저 하는 일은 로그를 찍어서 확인하는 것입니다. 이 페이지에서는 블루프린트의 Print String 노드와 C++의 UE_LOG, AddOnScreenDebugMessage를 사용해 로그를 출력하는 방법을 정리합니다.

Log

게임 개발을 하다가 원하는 동작 로직이 수행되지 않을 때, 보통 어떻게 하시나요?

대부분의 경우 if문으로 조건을 둔 뒤, C/C++에서 흔히 쓰는 printf나 cout으로 관련 내용을 출력하는 간단한 디버깅을 할 것입니다.

게임 개발에서는 이러한 예외 상황이 매우 많기 때문에, 일일이 로그를 찍어서 오류가 난 부분이 어디인지 빠르게 확인하는 것이 중요합니다.

언리얼 엔진 하단에는 이러한 로그를 관리하는 Output Log 탭이 따로 존재합니다. 탭의 Dock in Layout 버튼을 통해서 별도의 창으로 분리할 수도 있습니다.

로그를 모아서 보여주는 Output Log 탭

Log 출력(블루프린트)

블루프린트로 Log를 출력하려면 Print String 노드를 활용하면 됩니다.

BP_Item을 더블 클릭한 후, Event Graph 창에 들어가 우클릭한 다음 Print String을 검색하면 됩니다.

우클릭 후 Print String 검색

Print String 노드를 펼쳐보면 다음과 같이 구성되어 있습니다.

Print String 노드의 세부 속성

각 속성의 의미는 다음과 같습니다.

In String (입력 문자열)

화면이나 로그에 출력할 실제 텍스트 내용입니다.

Print to Screen (화면에 출력)

체크되어 있으면 게임 플레이 화면(뷰포트) 좌측 상단에 텍스트를 직접 띄워줍니다.

Print to Log (로그에 출력)

체크되어 있으면 언리얼 에디터 하단의 Output Log 창에 텍스트를 기록합니다.

Text Color (텍스트 색)

화면에 출력될 텍스트의 색상을 지정합니다. Print to Screen 전용입니다.

Duration (지속 시간)

화면에 텍스트가 표시되는 시간을 초 단위로 설정합니다. Print to Screen 전용입니다.

Key (고유 키)

일종의 덮어쓰기 기능입니다. Print to Screen 전용입니다.

• Key가 None이면 노드가 출력될 때마다 메시지가 위로 쌓입니다.
• Print String 노드가 2개 있고 두 노드의 Key가 같으면 메시지가 1번만 출력됩니다.
• Key가 서로 다르면 메시지가 2번 출력됩니다.

Output Log에 게임을 시작하자마자 Unreal Tutorial을 출력하려면 다음과 같이 노드를 연결하면 됩니다. (Event BeginPlay는 이 챕터 뒤에서 설명합니다.)

게임 시작 시 로그를 출력하도록 구성한 모습

이후 레벨에 BP_Item이 배치된 상태에서 게임 시작을 누르면 Output Log 창에 Unreal Tutorial이 출력되는지 확인해 봅니다.

Output Log에 표시된 실행 결과

여기서 단순히 Unreal Tutorial만 나오는 것이 아니라 LogBlueprintUserMessages: [BP_Item_C_1] Unreal Tutorial 형태로 출력됩니다. 각 부분의 의미는 다음과 같습니다.

• LogBlueprintUserMessages: Log의 카테고리입니다.
• [BP_Item_C_1]: Print String을 수행한 액터 인스턴스입니다.

Log의 카테고리는 원하는 Log를 좀 더 찾기 쉽게 하기 위해 정의된 기능입니다.

Output Log 상단의 Filters → Category Filters에서 현재 활성화된 카테고리 목록을 확인할 수 있습니다.

Filters > Category Filters 화면

여기서 모든 Log 카테고리를 체크 해제하고 LogBlueprintUserMessages 카테고리만 체크하면 해당 로그 1개만 남는 것을 볼 수 있습니다.

단일 카테고리만 필터링한 모습

이제 인게임 화면에서 Unreal Tutorial이라는 메시지를 10초간 하늘색으로 표시하려면 다음과 같이 설정하면 됩니다.

화면 출력용 속성 설정

이후 게임을 시작해 좌측 상단에 메시지가 출력되는지 확인합니다.

Print to Screen 실행 결과

Log 출력(C++)

C++에서도 게임 시작 시 Output Log에 로그를 출력하려면 UE_LOG() 매크로를 사용하면 됩니다.

기존에 작성한 Item 액터의 BeginPlay() 함수에 다음 내용을 작성합니다.

Item.cpp

void AItem::BeginPlay()
{
    Super::BeginPlay();

    UE_LOG(LogTemp, Warning, TEXT("Unreal C++ Tutorial")); // Unreal C++ Tutorial
}

각 인자의 의미는 순서대로 (카테고리 이름, 경고 수준, 출력할 메시지) 입니다.

• LogTemp는 엔진이 기본 제공하는 카테고리로, 이름에서 알 수 있듯 임시(temporary) 카테고리입니다.
• 경고 수준은 해당 로그가 얼마나 중요한지를 나타냅니다. Log(기본), Warning(경고), Error(오류) 등이 있으며 수준에 따라 로그의 색상이 결정됩니다.
• 출력할 메시지는 TEXT() 매크로를 사용해야 하며, 그 안에 문자열이 들어갑니다.

만약 문자열 안에 변수의 내용을 넣고 싶다면 C언어의 포맷 지정자를 사용하면 됩니다.

void AItem::BeginPlay()
{
    Super::BeginPlay();

    int32 n = 2;
    UE_LOG(LogTemp, Warning, TEXT("Unreal C++ Tutorial %d"), n); // Unreal C++ Tutorial 2
}

단, 문자열을 넣을 때는 앞에 *를 붙여야 합니다. 언리얼에서는 문자열 타입으로 FString을 사용합니다.

void AItem::BeginPlay()
{
    Super::BeginPlay();

    FString str(TEXT("Unreal C++ Tutorial"));
    UE_LOG(LogTemp, Warning, TEXT("%s"), *str); // Unreal C++ Tutorial
}

자신만의 커스텀 카테고리를 만들고 싶다면 헤더 파일에서 DECLARE_LOG_CATEGORY_EXTERN() 매크로를 사용하면 됩니다.

Item.h

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "Item.generated.h"

DECLARE_LOG_CATEGORY_EXTERN(TutorialLog, Log, All);

UCLASS()
class UNREALTUTORIAL_API AItem : public AActor
{
/* ... */
};

각 인자의 의미는 다음과 같습니다.

첫 번째 인자

새로 정의할 로그 카테고리의 이름을 지정합니다.

두 번째 인자

에디터에서 기본적으로 보여줄 기본 로그 수준입니다. 보통은 Log로 둡니다.

세 번째 인자

해당 카테고리의 로그를 특정 경고 수준 이상으로만 필터링하는 역할을 합니다. All은 모든 경고 수준의 로그를 찍을 수 있지만, Warning으로 두면 Warning 이상만 찍히고 Log 수준의 UE_LOG()는 무시됩니다.

다만 DECLARE_LOG_CATEGORY_EXTERN() 은 카테고리를 선언만 하기 때문에 구현(정의)도 해주어야 합니다. 이 부분은 .cpp 파일에서 DEFINE_LOG_CATEGORY() 매크로를 통해 구현합니다.

Item.cpp

#include "Item/Item.h"

DEFINE_LOG_CATEGORY(TutorialLog);

/* ... */

void AItem::BeginPlay()
{
    Super::BeginPlay();

    FString str(TEXT("Unreal C++ Tutorial"));
    UE_LOG(TutorialLog, Warning, TEXT("%s"), *str); // Unreal C++ Tutorial
}

/* ... */

아래는 게임 실행 시 출력되는 로그 화면입니다.

커스텀 로그 카테고리 출력 결과

다른 클래스에서 해당 카테고리를 사용하고 싶다면 카테고리를 선언한 헤더 파일을 include 하면 됩니다. 여기서는 Item.h가 됩니다.

#include "Item.h"

이제 화면에 메시지를 출력하고 싶다면 어떻게 해야 할까요? 블루프린트와 달리 한 곳에서 모든 것을 해결할 수는 없습니다.

참고

화면 출력 자체에는 UE_LOG()를 사용하지 않습니다. UE_LOG()는 Output Log에 기록하는 용도입니다.

C++에서 화면에 메시지를 띄우려면 GEngine->AddOnScreenDebugMessage() 함수를 사용할 수 있습니다.

GEngine->AddOnScreenDebugMessage(
    uint64 Key,
    float TimeToDisplay,
    FColor DisplayColor,
    FString DebugMessage,
    bool bNewerOnTop,
    FVector2D TextScale);

각 인자의 의미는 다음과 같습니다.

Key

Print String의 Key와 동일합니다. -1이 None과 동일합니다.

TimeToDisplay

Print String의 Duration과 동일합니다.

DisplayColor

Print String의 Text Color와 동일합니다.

DebugMessage

Print String의 In String과 동일합니다.

bNewerOnTop

새 메시지를 위로 보낼지 아래로 보낼지 결정합니다. 기본값은 true입니다.

TextScale

글자 크기 배율입니다. 기본값은 (1.0f, 1.0f)입니다.

블루프린트에서 했던 것처럼 게임 시작 시 Unreal Tutorial이라는 메시지를 파란색으로 10초간 띄우고 싶다면 다음과 같이 작성하면 됩니다.

void AItem::BeginPlay()
{
    Super::BeginPlay();

    if (GEngine)
    {
        GEngine->AddOnScreenDebugMessage(-1, 10.f, FColor::Blue, TEXT("Unreal Tutorial"));
    }
}

여기서 GEngine은 엔진의 전반적인 내용을 관리하는 전역 변수로, 렌더링과 물리 시뮬레이션, 디버깅 등을 담당합니다.

예외 처리 권장

GEngine이 늦게 활성화되는 경우를 대비하여 위 예시처럼 if로 GEngine의 유효성을 확인한 뒤 사용하면 더 안전합니다.

AddOnScreenDebugMessage 실행 결과

참고

다음 내용으로는 액터 라이프 사이클에 관해서 알아보겠습니다.