베르의 프로그래밍 노트

제대로 따라가기 (1) C++ 프로그래밍 튜토리얼 :: 변수, 타이머, 이벤트 (타이머를 사용하는 액터 만들기)

작성버전 :: 4.20.3

언리얼 엔진은 다양한 기능을 제공하며, 그 기능에 대한 튜토리얼들이 문서에 존재한다. 언리얼 엔진을 공부하기 위해선 필수적으로 이러한 튜토리얼들을 첫걸음으로 따라가게 되는데, 언리얼 튜토리얼 문서는 가끔 따라가다보면 제대로 진행이 안되고 막히는 부분이 존재한다. 튜토리얼은 배우는 단계인데 아직 엔진에 전혀 숙련되지 못한 사람이 이런 문제에 부딪히면 생각보다 많은 시간은 잡아먹게 된다. 제대로 따라가기는 이런 튜토리얼 도중에 막히는 부분을 빠르게 해소하고 따라가기 위해 제작되었다.

튜토리얼대로 하면 문제가 발생해서 제대로 따라갈 수 없는 부분으로 동작이 가능하게 수정해야하는 부분은 빨간 블럭으로 표시되어 있다.

이번 튜토리얼에서 새로 배우게 되는 내용은 글 제일 끝에 "이번 섹션에서 배운 것"에 정리된다.

변수, 타이머, 이벤트 (1. 타이머를 사용하는 액터 만들기)

변수, 타이머, 이벤트 튜토리얼은 변수와 함수를 에디터에 노출시키는 법, 타이머를 사용하여 코드 실행을 지연 또는 반복시키는 법, 이벤트를 사용하여 액터 사이의 통신을 하는 법을 알려주는 튜토리얼이다.

Countdown 클래스 추가

우선 C++ 프로젝트에서 Actor 클래스를 상속받는 Countdown 클래스를 생성하도록 한다.

카운트다운 진행 상황을 보여주기 위한 기능 추가

클래스가 생성되었다면 비주얼 스튜디오를 열어서 생성된 클래스에 카운트다운할 시간 변수와 카운트다운 진행 상황을 보여줄 텍스트 렌더 컴포넌트와 함수를 추가해야 한다. 그 예시 코드는 다음과 같다.

#pragma once

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

UCLASS()
class CODEPRACTICE_API ACountdown : public AActor
{
    GENERATED_BODY()
   
public:   
    // Sets default values for this actor's properties
    ACountdown();

protected:
    // Called when the game starts or when spawned
    virtual void BeginPlay() override;

public:   
    // Called every frame
    virtual void Tick(float DeltaTime) override;

    int32 CountdownTime;
   
    UTextRenderComponent* CountdownText;

    void UpdateTimerDisplay();
};

추가된 것은 int32 CountdownTime, UTextRenderComponent* CountdownText, void UpdateTimerDisplay()이다.

바로 이 부분에서 막히는 사람들이 꽤 많을 거라고 생각한다.

 

 

바로 UTextRenderComponent가 정의되어 있지 않다고 신텍스 에러가 뜨기 때문이다. 이 문제를 해결하기 위해서는 UTextRenderComponent가 정의된 헤더를 포함시켜줘야 한다. UTextRenderComponent 클래스는 Engine/Classes/Components/TextRenderComponent.h 에 정의되어 있다.

 

하지만 이 TextRenderComponent.h를 추가해야 된다는 걸 깨달았다고 모든 문제가 해결되지는 않았다. 바로 헤더 포함 순서 문제가 남아있기 때문이다. 습관적으로 새로 추가하는 헤더를 가장 뒤에 추가하는 프로그래머들이 많을텐데 언리얼 C++프로그래밍에서는 헤더를 포함할 때 순서를 지켜야 한다. 새로 추가되는 헤더는 무조건 generated.h보다 위쪽에서 추가되어야 한다.

#pragma once

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

#include "Engine/Classes/Components/TextRenderComponent.h"
#include "Countdown.generated.h"

UCLASS()
class CODEPRACTICE_API ACountdown : public AActor
{
    GENERATED_BODY()
   
public:   
    // Sets default values for this actor's properties
    ACountdown();

protected:
    // Called when the game starts or when spawned
    virtual void BeginPlay() override;

public:   
    // Called every frame
    virtual void Tick(float DeltaTime) override;

    int32 CountdownTime;
   
    UTextRenderComponent* CountdownText;

    void UpdateTimerDisplay();
};

위의 예시 코드처럼 generated.h 위의 적당한 위치에 TextRenderComponent.h를 포함시켜주면 신텍스 에러가 발생하지 않는다.

그 다음 작업은 ACountdown 클래스의 생성자에서 액터의 프로퍼티 값들을 초기화해주는 것이다. 언리얼 엔진 문서에서 제공하는 예시코드는 다음과 같다.

// Sets default values
ACountdown::ACountdown()
{
     // Set this actor to call Tick() every frame.  You can turn this off to improve performance if you don't need it.
    PrimaryActorTick.bCanEverTick = false;

    CountdownText = CreateDefaultSubobject(TEXT("CountdownNumber"));
    CountdownText->SetHorizontalAlignment(EHTA_Center);
    CountdownText->SetWorldSize(150.0f);
    RootComponent = CountdownText;

    CountdownTime = 3;
}

이 클래스에서 Tick 기능은 사용하지 않기 때문에 bCanEverTick은 false로 하고 CountdownText에 TextRenderComponent를 생성해서 루트 컴포넌트에 붙여주고 CountdownTime을 3초로 설정한다.

하지만 코드가 과거버전 기준으로 만들어지고 문서가 업데이트되지 않은 문제인지, CreateDefaultSubobject()함수를 호출하는 부분에서 신텍스 에러가 발생한다. 그래서 CreateDefaultSubobject() 함수를 살펴보면 템플릿 함수임을 알 수 있다.

CountdownText = CreateDefaultSubobject<UTextRenderComponent>(TEXT("CountdownNumber"));

CountdownText 변수가 받아야하는 UTextRenderComponent를 템플릿 파라미터에 넣어주면 문제없이 신텍스 에러가 사라진다.

그 다음은 아까 정의해둔 UpdateTimerDisplay() 함수를 구현하는 것이다. 이 함수는 남은 시간을 TextRenderComponent에 업데이트하고 시간이 다되면 0을 표시하도록 한다.

void ACountdown::UpdateTimerDisplay()
{
    CountdownText->SetText(FString::FromInt(FMath::Max(CountdownTime, 0)));
}

타이머(Timer)

화면에 대한 준비를 끝냈다면 이번에는 시간을 체크할 타이머를 추가할 차례다. 타이머란 사용자가 정의한 시간마다 사용자가 지정한 동작이 실행되도록 하는 것이다. 이러한 동작은 물론 Tick() 함수에서 DeltaTime 값을 받아서 같은 동작을 수행하도록 할 수는 있지만, 사용자가 지정한 동작이 지속적으로 실행될 필요가 없이 특정한 순간에만 몇 번 실행되면 되거나 실행될 텀이 1초를 넘는 경우라면 Tick() 함수에서 시간을 재서 실행하는 것보다는 타이머를 이용하는 편이 좋다.

타이머에 대해 이해가 되었다면 이제 타이머에 필요한 멤버 변수와 함수들을 Countdown.h의 Countdown 클래스의 하단에 추가해보자.

void AdvanceTimer();

void CountdownHasFinished();

FTimerHandle CountdownTimerHandle;

AdvanceTimer() 함수는 Timer가 돌아가면서 호출될 함수이다.

CountdownHasFinished() 타이머가 사용자가 의도한 만큼 돌아간 뒤의 처리를 위한 함수이다.

차량에 달린 핸들이 차량의 이동 방향을 컨트롤하기 위한 것이듯, FTimerHandle 역시 타이머를 컨트롤하기 위한 구조체로서 CountdownTimerHandle 변수는 카운트다운이 끝났을 때, 타이머가 계속해서 돌아가지 않도록 종료하기 위해서 필요하다.

AdvanceTimer() 함수와 CountdownHasFinished() 함수를 모두 정의했다면 이번에는 각 함수를 구현해보자.

void ACountdown::AdvanceTimer()
{
    --CountdownTime;
    UpdateTimerDisplay();
    if (CountdownTime < 1)
    {

        // 카운트다운이 완료되면 타이머를 중지
        GetWorldTimerManager().ClearTimer(CountdownTimerHandle);
        CountdownHasFinished();
    }
}

AdvanceTimer() 함수의 예시 코드는 위와 같은데 이 함수를 구현하면서 문제가 다시 발생한다. 이번에는 GetWorldTimerManager() 함수에서 ClearTimer() 함수를 호출할 때 "불완전한 형식은 사용할 수 없습니다." (E0070 :: Incomplete type is not allowed.) 라는 에러가 발생한다.

 

이 문제는 아래의 예시 코드와 같이 Countdown.cpp의 상단에 TimerManager.h를 포함시켜주면 해결된다.

// Fill out your copyright notice in the Description page of Project Settings.

#include "Countdown.h"
#include "TimerManager.h"

CountdownHasFinished() 함수의 코드는 다음과 같다.

void ACountdown::CountdownHasFinished()
{
    CountdownText->SetText(TEXT("Go!"));
}

다음 작업은 BeginPlay() 함수에서 텍스트 표시를 초기화하고 타이머를 동작시키는 것이다.

void ACountdown::BeginPlay()
{
    Super::BeginPlay();
   
    UpdateTimerDisplay();
    GetWorldTimerManager().SetTimer(CountdownTimerHandle, this, &ACountdown::AdvanceTimer, 1.0f, true);
}

에디터 컴파일과 레벨 배치 그리고 테스트 실행

모든 코드 작업이 끝났다면 이제 언리얼 에디터로 돌아가서 컴파일 버튼을 눌러보자. 

만약 컴파일 에러 없이 컴파일에 성공했다면 위의 이미지와 같이 컴파일 완료라고 에디터의 오른쪽 하단에 출력될 것이다.

컴파일이 완료된 다음에 우리가 작성한 Countdown 클래스를 레벨 에디터에 드래그 앤 드롭해서 배치할 수 있다.

배치를 완료했다면 플레이 버튼을 눌러서 실행해보자. 그러면 화면의 Text 글자가 3, 2, 1, Go!로 바뀌는 것을 확인할 수 있다.

이번 섹션에서 배운 것

1. CreateDefaultSubobject<T>() (언리얼 엔진 문서)

UObject 클래스를 상속받는 모든 클래스에서 사용가능한 함수이다. 하위 오브젝트나 컴포넌트를 생성할 때 사용되는 함수로 2번의 UTextRenderComponent를 생성하는 예시와 같이 사용된다. 이 함수는 T의 포인터(T*) 타입을 반환한다.

2. UTextRenderComponent(언리얼 엔진 문서)

UTextRenderComponent* TextRenderComponent;

설정된 텍스트를 3D 공간 상에 렌더링하는 컴포넌트이다. 글자 색, 크기, 폰트, 정렬 등을 설정할 수 있으며 액터 등에 컴포넌트로 덧붙여서 사용할 수 있다. 이 컴포넌트를 사용하기 위해서는 "Engine/Classes/Components/TextRenderComponent.h"를 포함해야 한다.

TextRenderComponent = CreateDefaultSubobject<UTextRenderComponent>(TEXT("TextRenderComponent"));

코드 상에서 UTextRenderComponent를 생성하는 방법은 위와 같다.

TextRenderComponent->SetHorizontalAlignment(EHTA_Center);

렌더링되는 텍스트의 수평 정렬을 설정하는 함수이다. 정렬 방식은 EHTA_Center, EHTA_Left, EHTA_Right가 있다.

TextRenderComponent->SetWorldSize(100.0f);

렌더링되는 텍스트의 월드에서의 크기를 설정하는 함수이다.

TextRenderComponent->SetText(TEXT("TEXT"));

렌더링되는 텍스트의 문자열 내용을 설정하는 함수이다.

3. Timer

타이머는 사용자가 정의한 시간마다 사용자가 지정한 동작이 실행되도록 만든다.

1) FTimerHandle (언리얼 엔진 문서)

FTimerHandle TimerHandle;

FTimerHandle은 타이머를 구별할 수 있는 유일한 핸들이다. 타이머를 생성하는 함수는 타이머를 생성할 때, 타이머의 핸들을 돌려주는데, 이 핸들을 가지고 있어야 생성한 타이머를 중지시킬 수 있다.

2) GetWorldTimerManager() (언리얼 엔진 문서)

AActor 클래스를 상속받는 모든 클래스에서 호출가능한 함수이다. 월드 타이머 매니저를 반환한다. GetWorldTimerManager()의 호출이 정상적으로 되지 않을 경우 "TimerManager.h"를 포함시키면 된다.

GetWorldTimerManager().SetTimer(TimerHandle, this, &ACountdown::AdvenceTimer, 1.0f, true);

SetTimer() 함수는 타이머를 생성하고 시작시키는 함수로 여러가지 오버로드가 존재하지만 우선은 위의 오버로드 형식만 살펴보자.

첫 번째 매개변수는 지금 생성되는 타이머의 핸들이다. 위에서 설명했듯이 이 핸들을 가지고 있어야 나중에 타이머를 종료할 수 있다.

두 번째 매개변수는 타이머 함수를 호출하는 오브젝트이다.

세 번째 매개변수는 타이머가 발동할 때마다 호출될 함수이다.

네 번째 매개변수는 타이머가 호출될 시간이다. 만약 값을 1로 두면 1초에 한 번씩 함수가 호출된다.

다섯 번째 매개변수는 타이머의 반복 여부이다. 만약 값이 false라면 타이머는 반복되지 않고 정해진 시간에 한 번만 호출된다.

GetWorldTimerManager().ClearTimer(TimerHandle);

ClearTimer() 함수는 돌아가고 있는 타이머를 중지시키고 해당 핸들을 무효화시키는 함수이다.

[투네이션]

[Patreon]

[디스코드 채널]

로그 출력하기

작성버전 :: 4.20.3

로그는 개발중에 여러가지 피드백을 얻기 위해서 중요한 도구다. 그렇기 때문에 항상 새로운 언어, 새로운 엔진 등을 배울 때는 거기서 어떤 방식으로 로그를 출력하는지 알아두는 것이 좋다. 이번에는 언리얼 엔진 4에서 로그를 출력하는 방법을 알아보자.

로그가 출력되는 출력 로그 탭 열기

우선은 로그를 출력하는 법을 배운 이후에 로그가 출력될 로그 탭을 여는 방법에 대해서 배워보자.

- 창 -> 개발자 툴 -> 출력 로그 (Window -> Developer Tools -> Output Log) 항목을 선택한다.

지시대로 출력 로그(Output Log) 항목을 선택하면 출력 로그 탭이 열리는 것을 확인할 수 있다. 에디터에서 우리가 출력하도록 명령한 로그들은 저 출력 로그 탭에서 출력될 것이다.

간단한 사용법

UE_LOG(LogTemp, Log, TEXT("Log Message"));

위의 코드를 사용하는 것으로 간단하게 로그를 출력할 수 있다. 언리얼에서 로그 기능은 매크로 함수로 정의 되어있으며, 매개변수는 앞에서부터 순서대로 로그 카테고리(Log Category), 로그 상세 수준(Log Verbosity Level), 로그 내용이다.

로그 상세 수준(Log Verbosity Level)

로그 상세 수준의 종류는 다음과 같다.

• Fatal

Fatal 수준 로그는 항상 콘솔 및 로그 파일에 출력되며 로그가 비활성화된 경우에도 작동이 중단된다.

• Error

Error 수준 로그는 콘솔 및 로그 파일에 출력되며, 이 로그는 기본적으로 빨간색으로 표시된다.

• Warning

Warning 수준 로그는 콘솔 및 로그 파일에 출력되며, 이 로그는 기본적으로 노란색으로 표시된다.

• Display

Display 수준 로그는 콘솔및 로그 파일에 출력된다.

• Log

Log 수준 로그는 로그 파일에는 출력되지만, 게임 내의 콘솔에서는 출력되지 않지만, 에디터의 출력 로그 탭을 통해서는 계속 출력된다.

• Verbose

Verbose 수준의 로그는 로그 파일에는 출력되지만, 게임 내의 콘솔에는 출력되지 않는다. 일반적으로 자세한 로깅 및 디버깅에 사용된다.

• VeryVerbose

VeryVerbose 수준의 로그는 로그 파일에는 출력되지만, 게임 내의 콘솔에는 출력되지 않는다. 이 수준의 로그는 일반적으로 대량의 로그를 출력하는 상세한 로깅에 사용된다.

로그 상세 수준 중에 자주 사용될 에러, 경고, 로그 수준을 사용해서 로그를 출력하면 위의 이미지와 같이 로그가 출력된다.

Fatal 수준의 로그는, 출력되거나 컴파일 혹은 빌드할 때 코드가 실행되는 상황이라면 충돌 리포트를 띄우지만 이것은 의도된 충돌이기 때문에 로그 파일이나 충돌 호출 스택(Crash call stack)을 확인하면 된다.

로그 카테고리(Log Category)

로그 카테고리는 출력된 로그가 어떤 시스템에서 발생한 로그인지 알려주는 역할을 한다. 위의 간단한 사용법 파트에서는 이 로그 카테고리에 LogTemp를 넣어서 사용했는데, 이것은 특정한 카테고리에 속하지 않고 임시로 띄우는 로그라는 의미다. 언리얼 엔진에서는 이러한 카테고리를 90개 이상을 기본적으로 제공한다.

어떤 카테고리에서 로그가 발생했는지 알려줄 수 있기 때문에 로그 출력 코드를 작성할 때, 제대로 된 카테고리를 분류해서 넣어주기만 한다면 로그가 제공하는 정보가 좀 더 상세해질 수 있다.

커스텀 로그 카테고리(Custom Log Category)

언리얼 엔진에서 제공하는 로그 카테고리 이외에 개발자가 필요한 카테고리를 직접 만들어서 사용할 수 있다.

만약, 당신의 프로젝트 이름이 MyGame이라면 비주얼 스튜디오의 솔루션 탐색기에서 MyGame.h와 MyGame.cpp를 찾아서 다음과 같이 추가하면 된다.

MyGame.h

// Fill out your copyright notice in the Description page of Project Settings.

#pragma once

#include "CoreMinimal.h"

DECLARE_LOG_CATEGORY_EXTERN(LogMyGame, Log, All);

MyGame.cpp

// Fill out your copyright notice in the Description page of Project Settings.

#include "MyGame.h"
#include "Modules/ModuleManager.h"

IMPLEMENT_PRIMARY_GAME_MODULE( FDefaultGameModuleImpl, MyGame, "MyGame" );

DEFINE_LOG_CATEGORY(LogMyGame);

그리고 추가한 로그 카테고리를 사용할 때는 아래의 예시 코드와 같이 사용할 소스 파일에 MyGame.h를 포함한뒤 사용하면 된다.

MyActor.cpp

// Fill out your copyright notice in the Description page of Project Settings.

#include "MyActor.h"
#include "Engine.h"
#include "MyGame.h"

// Sets default values
AMyActor::AMyActor()
{
     // Set this actor to call Tick() every frame.  You can turn this off to improve performance if you don't need it.
    PrimaryActorTick.bCanEverTick = true;

    UE_LOG(LogMyGame, Log, TEXT("My Log"));
}

로그 포맷(Log Formatting)

로그를 작성할 때, 로그의 내용이 고정되어 있는 경우보다, 상황이나 데이터의 내용에 따라 유동적으로 바뀌는 경우가 많다. 그렇기 때문에 간단한 사용법 파트의 예시처럼 고정된 문자열 방식이 아니라 포맷팅을 통해서 원하는 데이터의 내용 등을 고정된 로그의 내용과 함께 출력되도록 해야한다. 언리얼 엔진에서 로그 포맷팅을 하는 방법은 CPP에서 문자열 포맷팅하는 방법과 같다.

일반 메시지

UE_LOG(LogTemp, Log, TEXT("Log Message"));

FString

언리얼 엔진에서 기본적으로 사용되는 문자열 클래스는 FString이다. 로그에서 %s는 TCHAR* 타입을 받는다. 이것은 *FString에 대응한다.

UE_LOG(LogTemp, Log, TEXT("Character Name :: %s"), *MyCharacter->GetName());

bool

UE_LOG(LogTemp, Log, TEXT("Character is Die :: %s"), MyCharacter->IsDie ? TEXT("true") : TEXT("false"));

int

UE_LOG(LogTemp, Log, TEXT("Character HP :: &d"), MyCharacter->Hp);

float

UE_LOG(LogTemp, Log, TEXT("Character Stamina :: %f"), MyCharacter->Stamina);

FVector

FVector는 언리얼 엔진에서 위치를 표현하는 클래스이다.

UE_LOG(LogTemp, Log, TEXT("Character Location :: %s"), MyCharacter->GetActorLocation().ToString());

FName

UE_LOG(LogTemp, Log, TEXT("Character FName :: &d"), MyCharacter->GetFName().ToString());

여러 자료형 한번에 로그로 출력하기

UE_LOG(LogTemp, Log, TEXT("CharacterName :: &s / HP :: &d / Stamina :: %f"), *MyCharacter->GetName(), MyCharacter->Hp, MyCharacter->Stamina);

추가로...

bool 같은 논리 변수는 로그로 출력하는 과정이 조금 번거롭기 때문에, 로그를 자주 사용한다면 이러한 번거로운 과정을 간소화하기 위해서 로그를 위한 클래스로 래핑해서 사용하는 것도 추천해볼만하다.

참고

Unreal Engine 4 Wiki - Logs, Printing Messages To Yourself During Runtime (https://wiki.unrealengine.com/index.php?title=Logs,_Printing_Messages_To_Yourself_During_Runtime&action=edit)

[투네이션]

[Patreon]

[디스코드 채널]

프로그래밍 작업시 헤더(Header) 포함(Include) 문제

작성버전 :: 4.20.3

언리얼 엔진4(이하 언리얼 엔진 혹은 언리얼)에서의 프로그래밍은 C++기반으로 구성되어 있기 때문에 다른 헤더 파일에 정의된 클래스 등을 사용하기 위해서는 헤더를 포함하는 전처리가 필수적이다.

일반적인 C++ 프로젝트에서 헤더가 꼬이거나 중복 호출되는 경우만 조심하면 주의하면 되고 헤더의 순서는 별로 중요하지 않은 것에 비해서 언리얼에서의 헤더 포함은 약간 복잡하고 귀찮은데다가 버그까지 있다.

언리얼 엔진이 아닌 다른 C++ 프로젝트에서는 프로그래밍 작업 도중에 필요한 헤더가 생긴다면 상단의 전처리기들 아래에 필요한 헤더의 포함 선언을 추가할 것이다. 하지만 언리얼에서는 헤더 포함의 위치가 중요하다.

만약 AMyActor 클래스에서 AMyActorComponent를 사용하기 위해서 MyActorComponent.h의 선언을 일반적인 C++ 프로젝트에서 하듯이 MyActor.h의 헤더 포함 리스트 제일 아래에 추가하면 위의 이미지처럼 신텍스 에러(E0077 this declaration has no storage class or type specifier)가 발생하고 에디터에서의 컴파일 역시 실패한다.

언리얼에서는 다른 헤더를 포함할 때, 항상 generated.h 헤더보다 위쪽에 포함 선언을 추가해야 된다.

위의 이미지처럼 새롭게 추가하는 헤더 포함 선언을 generated.h 헤더 선언 위로 올리고 수정한 소스 파일을 저장하면 대부분은 신텍스 에러가 사라진다. 하지만 여기서 고질적인 문제가 발생하는데 꽤나 높은 빈도로 정상적으로 generated.h 위쪽으로 헤더 포함 선언을 옮겼는데도 불구하고 아래의 이미지처럼 신텍스 에러가 사라지지 않는 경우가 있다.

이러한 문제는 인텔리전스 버그로 실제 컴파일에서는 전혀 문제가 되지 않는다. 실제로도 에디터에서 컴파일을 해보면 전혀 문제 없이 컴파일이 진행되는 것을 알 수 있다. 이런 인텔리전스 버그는 잠시 후에 없어지기도 하고, 에디터에서 컴파일하거나, 비주얼 스튜디오나 언리얼을 재실행 하는 것으로도 없어진다.

이런 헤더 순서 문제가 매우 중요함에도 불구하고 언리얼 엔진 레퍼런스 문서에서는 쉽게 찾을 수 없는게 문제다.

[투네이션]

[Patreon]

[디스코드 채널]