프로젝트 구성 및 컴파일하기 | 언리얼 엔진 5.6 문서

시작하기 전에

다음 사항을 확인해 주세요.

언리얼 엔진을 설치했고 언리얼 엔진용 Visual Studio를 구성했는지 확인합니다.
프로젝트와 액터에 대해 학습했고 언리얼 에디터 탐색 방법을 익혔는지 확인합니다.
1인칭 어드벤처 게임 코딩하기를 읽었는지 확인합니다.

템플릿에서 시작하기

이 튜토리얼에서는 샘플 에셋이 포함된 블루프린트 기반 프로젝트로 시작합니다. 기존 블루프린트 함수 기능을 복제하고 확장하는 코드를 차근차근 추가할 것입니다. 이렇게 하면 새로운 C++ 프로젝트에서 새 클래스를 빌드하는 방법을 배우면서 동일한 블루프린트를 레퍼런스로 사용할 수 있습니다.

템플릿에서 새 게임 프로젝트를 생성하려면 다음 단계를 따릅니다.

언리얼 엔진을 엽니다. 언리얼 프로젝트 브라우저(Unreal Project Browser)에서 게임(Games) 프로젝트 카테고리로 이동하여 1인칭(First Person) 템플릿을 선택합니다.
프로젝트 디폴트(Project Default)에서 프로젝트 타입을 블루프린트(Blueprint)로 설정합니다. 즉, 언리얼 엔진은 C++ 에셋 대신 블루프린트 타입의 디폴트 에셋으로 프로젝트를 생성합니다.
베리언트(Variant)의 경우, 아레나 슈터(Arena Shooter)를 선택합니다.
프로젝트를 명명합니다. 이 튜토리얼에서는 AdventureGame을 프로젝트 이름으로 사용합니다.
생성(Create)을 클릭하여 에디터에서 새 프로젝트를 엽니다.

향상된 입력 검증하기

향상된 입력(Enhanced Input) 시스템을 사용하면 점프나 웅크리기 등, 캐릭터가 할 수 있는 동작을 정의하는 커스텀 입력 액션(Input Action)을 생성하여 캐릭터 무브먼트를 제어할 수 있습니다. 각 입력 액션은 코드에서 참조하여 코드와 캐릭터 간에 통신할 수 있는 데이터 에셋으로 존재합니다.

이 튜토리얼의 뒷부분에서는 입력 액션과 코드를 결합하여 캐릭터가 움직이고 주변을 둘러볼 수 있게 할 것입니다.

향상된 입력 시스템은 프로젝트에서 이미 활성화되어 있어야 합니다. 활성화되었는지 검증하려면 다음 단계를 따릅니다.

언리얼 에디터의 메인 메뉴에서 편집(Edit) 메뉴로 이동하여 플러그인(Plugins)을 선택합니다.
Enhanced Input(향상된 입력)을 검색합니다. 플러그인이 설치되고 활성화된 것이 보일 것입니다.

향상된 입력 시스템 및 입력 액션에 대한 자세한 내용은 향상된 입력을 참조하세요.

C++ 게임 모드 클래스 생성하기

블루프린트 기반 프로젝트에는 작업할 C++ 파일이나 Visual Studio(VS) 프로젝트가 없습니다. 다음으로 첫 번째 클래스를 생성하고 프로젝트에 C++를 도입합니다. 시작하려면 언리얼 엔진이 코딩에 필요한 Visual Studio 프로젝트와 파일을 생성하도록 지시하는 커스텀 게임 모드(Game Mode) 클래스를 생성합니다. 커스텀 클래스는 부모 AGameModeBase 클래스에서 파생됩니다.

게임 모드 에셋은 게임의 규칙, 승리 조건, 사용되는 캐릭터를 정의합니다. 게임 모드는 폰(Pawn)과 플레이어 컨트롤러(PlayerController), HUD를 포함하여 프로젝트에서 사용하는 디폴트 게임플레이 프레임워크 클래스도 설정합니다. 이 튜토리얼 후반부에서는 게임 모드를 사용하여 디폴트 플레이어 캐릭터를 변경합니다.

새 게임 모드 C++ 클래스를 생성하려면 다음 단계를 따릅니다.

언리얼 에디터의 메인 메뉴에서 툴(Tools) > 새 C++ 클래스(New C++ Class)로 이동합니다.
부모 클래스 선택(Choose Parent Class) 창에서 게임 모드 베이스(Game Mode Base)를 찾아서 선택하고 다음(Next)을 클릭합니다.
새 클래스의 이름을 입력한 다음 클래스 생성(Create Class)을 클릭합니다. 이 튜토리얼에서는 AdventureGameMode라는 이름을 사용합니다.
콘텐츠 브라우저에 C++ 클래스를 표시하려면 먼저 VS에서 한 번 이상 프로젝트를 빌드하거나 컴파일해야 한다는 경고 메시지가 두 번 표시됩니다. 확인(OK)을 클릭한 다음, 두 번째 경고가 표시되면 예(Yes)를 클릭하여 코드를 엽니다.

프로젝트 빌드하기

코드를 추가하기 전에 VS에서 프로젝트를 빌드하고 언리얼 에디터를 새로 고쳐 환경 준비를 마무리합니다.

Visual Studio에서 프로젝트를 열기

게임 모드 클래스를 생성한 후 엔진 내에서 VS에서 프로젝트를 열라는 메시지가 자동으로 표시되지 않는 경우, 언리얼 에디터 메인 메뉴의 툴(Tools)로 이동하여 Visual Studio 열기(Open Visual Studio)를 선택합니다.

아니면 프로젝트의 .sln 파일을 찾아 열어도 되는데, 해당 파일은 디폴트로 /Documents/Unreal Projects/[프로젝트명]에 있습니다.

언리얼 엔진은 새 클래스, 모듈, 플러그인을 추가 및 빌드 세팅의 수정 등 프로젝트에 적용한 변경사항을 트래킹합니다. 그러나 VS 프로젝트 파일에는 이러한 업데이트가 자동으로 반영되지 않을 수도 있습니다. 툴 메뉴의 Visual Studio 프로젝트 새로고침(Refresh Visual Studio Project)을 사용하여 현재 프로젝트 스테이트를 기반으로 솔루션 및 프로젝트 파일을 재생성하면 모든 항목을 최신 상태로 유지할 수 있습니다.

Visual Studio를 열면 Solution Explorer에 프로젝트 파일이 정리되어 있는 것을 볼 수 있습니다.

VS에서 첫 번째 언리얼 엔진 C++ 프로젝트를 처음 열면 Solution Explorer에 컴포넌트 누락 경고가 표시될 수 있습니다. Install을 클릭하여 VS가 프로젝트에 필요할 수 있는 추가 컴포넌트를 설치하도록 허용합니다.

Solution Explorer에서 Games > [프로젝트명] > Source > [프로젝트명]을 엽니다. 여기는 게임의 주요 파일들이 위치한 곳으로, 새 게임 모드에 해당하는 [게임 모드명].cpp와 [게임 모드명].h 두 파일도 포함되어 있습니다.

프로젝트 빌드 및 언리얼 에디터 새로고침

언리얼 에디터가 코드 프로젝트를 인식하고 콘텐츠 브라우저에 C++ 클래스를 포함하도록 하려면, VS에서 프로젝트를 빌드하고 에디터를 재시작해야 합니다.

언리얼 에디터에 클래스가 표시되도록 프로젝트를 빌드하려면 다음 단계를 따릅니다.

Solution Explorer의 Games > [프로젝트명]에서 프로젝트를 우클릭하고 Build를 선택합니다.
빌드가 완료되면 언리얼 에디터로 돌아가 하단 툴바에 컴파일(Compile) 버튼이 표시되는지, 콘텐츠 브라우저에 새 C++ 클래스 폴더가 표시되는지 확인합니다.
표시되지 않으면 에디터를 닫고 프로젝트를 다시 엽니다. 에디터를 열면 프로젝트가 리컴파일되면서 UE에 C++ 클래스가 있다고 알립니다. 언리얼 엔진에서 프로젝트를 리빌드할지 묻는 메시지가 표시되면 예(Yes)를 클릭합니다.

라이브 코딩 비활성화

코드를 다시 컴파일하기 전에 언리얼 에디터에서 라이브 코딩(Live Coding)을 비활성화합니다. 라이브 코딩을 사용하면 엔진이 실행되는 동안 구현(.cpp) 파일에서 C++ 코드를 변경하고 리빌드할 수 있지만, 컴파일 워크플로가 달라서 헤더(.h) 파일을 편집하거나 Visual Studio에서 컴파일을 시도할 때 오류가 발생할 수 있습니다. 라이브 코딩은 개발된 코드 베이스를 반복작업할 때 유용하지만, 새 프로젝트를 시작할 때는 비활성화하는 것이 좋습니다.

라이브 코딩을 비활성화하려면 에디터 하단 툴바에서 컴파일 버튼 옆의 점 3개를 클릭하고 라이브 코딩 활성화(Enable Live Coding)를 비활성화합니다.

C++ 클래스를 블루프린트로 확장하기

이제 커스텀 게임 모드를 만들었으니, 이 모드를 블루프린트로 확장하여 프로퍼티를 에디터에 노출한 다음 새 블루프린트를 프로젝트의 디폴트 게임 모드로 설정합니다.

게임 모드 클래스를 블루프린트로 확장하면 코드로 모든 것을 처리하는 대신, 클래스 값이 에디터에 직접 노출됩니다. 블루프린트는 C++ 클래스의 자손처럼 작동하며 C++ 클래스의 모든 함수 기능을 상속합니다.

게임 모드 클래스에서 블루프린트 에셋을 파생하려면 다음 단계를 따릅니다.

콘텐츠 브라우저 에셋 트리에서 C++ 클래스 > [프로젝트명]으로 이동하여 생성한 C++ 클래스를 찾습니다.
게임 모드 베이스(Game Mode Base) 클래스를 우클릭하고 [게임 모드 베이스명] 기반으로 블루프린트 클래스 생성(Create Blueprint class based on [GameModeBaseName])을 선택합니다.
블루프린트 클래스 추가(Add Blueprint Class) 창에서 BP_ 접두사를 붙여 나중에 식별할 수 있는 이름으로 블루프린트 이름을 짓습니다. 이 튜토리얼에서는 BP_AdventureGameMode라는 이름을 사용합니다.
경로(Path)의 경우, 모두(All) > 콘텐츠(Content) > 1인칭(FirstPerson) > 블루프린트(Blueprints)를 선택한 다음, 클래스 생성(Create Class)을 클릭합니다.
언리얼 엔진은 새 블루프린트 에디터 창에서 자동으로 블루프린트를 엽니다.

메인 에디터 창에서 블루프린트의 탭을 맵 탭(Lvl_FirstPerson) 옆에 드래그하여 메인 에디터 창 내에서 새 창을 도킹할 수 있습니다.

프로젝트의 게임 모드 변경하기

기본적으로 새 언리얼 엔진 프로젝트는 샘플 게임 모드를 사용합니다. 이 부분을 커스텀 게임 모드로 변경하려면 프로젝트 세팅을 편집하면 됩니다.

디폴트 게임 모드를 변경하려면 다음 단계를 따릅니다.

에디터의 메인 메뉴에서 편집(Edit) > 프로젝트 세팅(Project Settings)으로 이동합니다.
왼쪽 패널의 프로젝트(Project) 섹션에서 맵 & 모드(Maps & Modes)를 선택합니다.
세팅 테이블 상단에서 기본 게임 모드(Default GameMode)를 사용하려는 게임 모드 블루프린트로 변경합니다.
프로젝트 세팅을 닫습니다.
메인 메뉴에서 창(Window) > 월드 세팅(World Settings)으로 이동합니다. 기본적으로 월드 세팅(World Settings) 패널은 디테일(Details) 패널 옆에 도킹되어 표시됩니다. 이러한 세팅은 현재 레벨의 동작 방식을 제어합니다.
게임 모드(Game Mode) 섹션에서 게임 모드 오버라이드(GameMode Override)를 새 게임 모드 블루프린트로 설정합니다.
샘플 레벨에 대해서는 게임 모드 오버라이드만 변경하면 됩니다. 새 기본 레벨을 생성하면 게임 모드 오버라이드(GameMode Override)가 기본적으로 없음(None)으로 설정됩니다.

스크린 디버그 메시지 추가하기

프로젝트에 코드 추가를 시작하는 좋은 방법은 화면에 'Hello World!' 메시지를 추가하는 것입니다.

디버그 메시지를 추가하여 언리얼 엔진에서 제공하는 기본 게임모드가 아닌, 새 게임 모드를 사용하고 있는지 검증합니다. 로그 메시지와 디버그 메시지는 개발 과정에서 코드를 검증하고 디버깅하는 데에 매우 유용합니다.

디폴트 StartPlay() 함수 오버라이드하기

AGameModeBase에는 게임이 게임플레이를 시작할 준비가 되면 UE가 호출하는 StartPlay() 함수가 포함되어 있습니다. 일반적으로 커스텀 게임 모드 클래스에서 이 함수를 오버라이드하여 글로벌 게임 시작 로직을 추가합니다. 여기서는 게임 시작 시 디버그 메시지가 표시되도록 오버라이드합니다.

커스텀 게임 모드 클래스에서 StartPlay()를 오버라이드하려면 다음 단계를 따릅니다.

VS에서 게임 모드 클래스의 .h 헤더 파일을 엽니다. 이 튜토리얼의 코드 샘플에서는 AdventureGameMode라는 클래스를 사용합니다.
디폴트 코드는 다음과 같은 모습이어야 합니다.
C++
```
UCLASS()
class ADVENTUREGAME_API AAdventureGameMode : public AGameModeBase
{
	GENERATED_BODY()
	
};
```
UCLASS() class ADVENTUREGAME_API AAdventureGameMode : public AGameModeBase { GENERATED_BODY() };
GENERATED_BODY()는 언리얼 헤더 툴에서 사용하는 매크로로서, 이 클래스 및 기타 UObject가 언리얼 엔진에서 작동하는 데 필요한 코드를 자동으로 생성합니다. 언리얼 헤더 툴에 대해 자세히 알아보려면 UHT 문서를 참고하세요.
AAdventureGameMode 클래스는 게임 시작 또는 종료, 맵 진입, 진행 중인 게임 등 다양한 게임 모드 스테이트를 코드에 노출합니다. 각 스테이트가 트리거되면 StartPlay()나 ResetLevel()과 같은 연결된 함수를 실행합니다.
StartPlay() 함수에 대한 오버라이드 선언을 AAdventureGameModeBase 클래스에 추가합니다.
C++
```
UCLASS()
class ADVENTUREGAME_API AAdventureGameMode : public AGameModeBase
{
	GENERATED_BODY()

	virtual void StartPlay() override;	
};
```
UCLASS() class ADVENTUREGAME_API AAdventureGameMode : public AGameModeBase { GENERATED_BODY() virtual void StartPlay() override; };
.h 파일을 저장합니다.

언리얼 엔진 클래스와 함수에는 언리얼 헤더 툴에 클래스 타입을 알려주는 접두사가 있습니다. 예를 들어, 액터에는 A, UObject에는 U, 구조체에는 F를 접두사로 사용합니다. 언리얼 엔진 C++ 클래스 접두사에 대한 자세한 내용은 에픽 C++ 코딩 표준 문서의 명명 규칙 섹션을 참고하세요.

StartPlay()에 디버그 메시지 추가하기

디버그 메시지를 출력하는 몇 가지 커스텀 코드와 함께 StartPlay() 오버라이드를 구현합니다.

게임플레이가 시작될 때 화면에 디버그 메시지를 출력하려면 다음 단계를 따릅니다.

게임 모드의 .cpp 파일을 열어 방금 선언한 함수를 구현합니다.
StartPlay()에 대한 새 함수 정의를 추가합니다. 이 함수는 AAdventureGameMode에 선언되어 있으므로 AAdventureGameMode::StartPlay()를 사용하여 정의합니다.
C++
```
void AAdventureGameMode::StartPlay()
{

}
```
void AAdventureGameMode::StartPlay() { }
AMyGameModeBase::StartPlay() 안에 Super::StartPlay()를 추가하여 AAdventureGameMode 부모 클래스에서 StartPlay() 함수를 호출합니다. 이는 게임이 시작될 때 실행되어야 하는 다른 로직을 처리하는 데 필요합니다.
다음으로, 글로벌 엔진 포인터가 유효한지 확인하기 위해 GEngine != nullptr에 대한 check를 추가합니다.
C++
```
void AAdventureGameMode::StartPlay()
{
	Super::StartPlay();

	check(GEngine != nullptr);
}
```
void AAdventureGameMode::StartPlay() { Super::StartPlay(); check(GEngine != nullptr); }
이는 언리얼 엔진 자체가 사용하는 UEngine 클래스에 대한 포인터로, 이 포인터가 유효한지 확인하면 코드를 계속 실행하기 전에 게임이 제대로 실행되고 있는지 확인할 수 있습니다. 글로벌 엔진 포인터가 유효하지 않으면 게임이 크래시됩니다.
GEngine을 사용하여 게임이 실행 중일 때 화면에 메시지를 출력하는 UEngine의 AddOnScreenDebugMessage() 멤버 함수에 액세스합니다.
이 함수는 다음의 네 가지 값을 받습니다.
- 메시지를 식별하고 동일한 메시지가 여러 번 추가되는 것을 방지하는 고유한 int 키. 고유성이 중요하지 않은 경우 -1을 사용합니다.
- 메시지를 표시할 시간(초)을 나타내는 플로트 숫자.
- 텍스트 컬러를 설정하는 FColor.
- 출력할 FString 메시지.
다음 값을 사용하면 게임이 시작될 때 5초 동안 화면에 노란색 텍스트로 'Hello World!' 메시지가 표시됩니다.
C++
```
GEngine->AddOnScreenDebugMessage(-1, 5.0f, FColor::Yellow, TEXT("Hello World, this is AdventureGameMode!"));
```
GEngine->AddOnScreenDebugMessage(-1, 5.0f, FColor::Yellow, TEXT("Hello World, this is AdventureGameMode!"));
.cpp 파일을 저장합니다.

이제 AAdventureGameMode::StartPlay()는 다음과 같은 모습이어야 합니다.

C++

#include "AdventureGameMode.h"

void AAdventureGameMode::StartPlay()
{
	Super::StartPlay();

	check(GEngine != nullptr);

	GEngine->AddOnScreenDebugMessage(-1, 5.0f, FColor::Yellow, TEXT("Hello World!"));
}

#include "AdventureGameMode.h"

void AAdventureGameMode::StartPlay()
{
	Super::StartPlay();

	check(GEngine != nullptr);

	GEngine->AddOnScreenDebugMessage(-1, 5.0f, FColor::Yellow, TEXT("Hello World!"));
}

UE_LOG는 디버그 메시지를 출력하는 데 유용한 또 다른 함수입니다. 화면에 메시지를 출력하는 대신, 런타임 중에 언리얼 엔진의 출력 로그나 콘솔에 메시지를 기록합니다. 이는 게임에서 일어나는 일에 대한 자세한 정보를 기록하거나 트래킹하는 데 유용합니다. 로그를 여러 채널로 분류하고 정보, 오류 또는 경고 메시지 등으로 메시지 타입을 정의할 수 있습니다. 예시:

UE_LOG(LogTemp, Warning, TEXT("경고 메시지입니다!"));

코드 컴파일 및 테스트

언리얼 에디터에서 컴파일 버튼을 클릭하여 프로젝트를 리빌드할 수 있지만, VS에서 리빌드하는 것을 권장합니다. 컴파일이 완료되면 에디터와 게임 내에서 코드 변경사항이 반영된 것을 확인할 수 있습니다.

게임에서 변경사항을 확인하려면 메인 툴바에서 플레이(Play)를 클릭하여 에디터에서 플레이(Play in Editor, PIE) 모드를 시작합니다. 디버그 메시지가 왼쪽 상단에 표시됩니다.

PIE 모드를 종료하려면 레벨 에디터 툴바에서 Shift + Escape를 누르거나 중지(Stop)를 클릭합니다.

다음 순서

이제 새로운 게임 모드가 포함된 기초 프로젝트가 있으니 플레이어 캐릭터 제작을 시작할 수 있습니다! 다음 섹션에서는 새 캐릭터 클래스를 빌드하고 입력 액션을 사용하여 캐릭터에 무브먼트 컨트롤을 추가하는 방법을 배웁니다.

입력 액션으로 플레이어 캐릭터 생성하기

입력 액션으로 C++ 캐릭터 빌드를 시작하는 방법을 살펴봅니다.

완성된 코드

이 섹션에서 빌드한 완성된 코드는 다음과 같습니다.

C++

AdventureGameMode.h

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/GameModeBase.h"
#include "AdventureGameMode.generated.h"

UCLASS()
class ADVENTUREGAME_API AAdventureGameMode : public AGameModeBase
{
	GENERATED_BODY()

C++

AdventureGameMode.cpp

#include "AdventureGameMode.h"

void AdventureGameMode::StartPlay()
{
	Super::StartPlay();

	check(GEngine != nullptr);

	GEngine->AddOnScreenDebugMessage(-1, 5.0f, FColor::Yellow, TEXT("Hello World!"));
}

#include "AdventureGameMode.h"

void AdventureGameMode::StartPlay()
{
	Super::StartPlay();

	check(GEngine != nullptr);

	GEngine->AddOnScreenDebugMessage(-1, 5.0f, FColor::Yellow, TEXT("Hello World!"));
}