첫 번째 언리얼 C++ 프로젝트 생성

이 절에서는 언리얼 엔진에서 C++ 프로젝트를 처음 생성하고 기본 구조를 이해하는 과정을 안내합니다.

새 프로젝트 생성

Epic Games Launcher를 실행하고 언리얼 엔진 탭으로 이동합니다.
"시작" 버튼을 클릭하여 프로젝트 브라우저를 엽니다.
"새 프로젝트" 탭을 선택하고, C++ 프로젝트 템플릿을 선택합니다.
프로젝트 설정을 구성합니다.

프로젝트 이름 설정 (예 : MyFirstCppProject)
프로젝트 저장 위치 선택
선택한 템플릿에 따른 추가 설정 구성

"프로젝트 생성" 버튼을 클릭합니다.

프로젝트 구조 이해

생성된 프로젝트의 폴더 구조는 다음과 같습니다.

MyFirstCppProject/
├── Config/
├── Content/
├── Source/
│   ├── MyFirstCppProject/
│   │   ├── MyFirstCppProject.Build.cs
│   │   ├── MyFirstCppProject.cpp
│   │   ├── MyFirstCppProject.h
│   │   └── MyFirstCppProjectGameMode.cpp
│   └── MyFirstCppProjectEditor/
├── MyFirstCppProject.uproject
└── MyFirstCppProject.sln

주요 폴더 및 파일 설명

Config/ : 프로젝트 설정 파일들이 저장됩니다.
Content/ : 게임 에셋 파일들이 저장됩니다.
Source/ : C++ 소스 코드가 위치합니다.
MyFirstCppProject.uproject : 프로젝트 설정 파일입니다.
MyFirstCppProject.sln : Visual Studio 솔루션 파일입니다.

Source 폴더 구조

1. MyFirstCppProject/ : 메인 게임 모듈

MyFirstCppProject.Build.cs : 프로젝트 빌드 설정 파일
MyFirstCppProject.cpp/.h : 게임 모듈 정의 파일
MyFirstCppProjectGameMode.cpp : 기본 게임 모드 클래스

2. MyFirstCppProjectEditor/ : 에디터 전용 모듈 (있는 경우)

C++ 클래스 추가

언리얼 에디터에서 File > New C++ Class를 선택합니다.
부모 클래스를 선택합니다 (예 : Actor).
클래스 이름을 입력합니다 (예 : MyFirstActor).
"Create Class" 버튼을 클릭합니다.

생성된 클래스 파일 구조

// MyFirstActor.h
##pragma once
 
##include "CoreMinimal.h"
##include "GameFramework/Actor.h"
##include "MyFirstActor.generated.h"
 
UCLASS()
class MYFIRSTCPPPROJECT_API AMyFirstActor : public AActor
{
    GENERATED_BODY()
    
public:    
    AMyFirstActor();
 
protected:
    virtual void BeginPlay() override;
 
public:    
    virtual void Tick(float DeltaTime) override;
};
 
// MyFirstActor.cpp
##include "MyFirstActor.h"
 
AMyFirstActor::AMyFirstActor()
{
    PrimaryActorTick.bCanEverTick = true;
}
 
void AMyFirstActor::BeginPlay()
{
    Super::BeginPlay();
}
 
void AMyFirstActor::Tick(float DeltaTime)
{
    Super::Tick(DeltaTime);
}

언리얼 엔진 특유의 매크로와 클래스 선언

UCLASS() : 언리얼 엔진의 리플렉션 시스템에 클래스를 등록합니다.
GENERATED_BODY() : 언리얼 엔진의 타입 시스템에 필요한 보일러플레이트 코드를 생성합니다.
MYFIRSTCPPPROJECT_API : DLL 익스포트 매크로로, 해당 클래스를 모듈 외부에서 사용할 수 있게 합니다.

간단한 C++ 코드 추가 및 컴파일

MyFirstActor 클래스에 간단한 기능을 추가해 봅시다.

// MyFirstActor.h
public:
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="My Variables")
    float MyFloat;
 
    UFUNCTION(BlueprintCallable, Category="My Functions")
    void MultiplyMyFloat(float Multiplier);
 
// MyFirstActor.cpp
void AMyFirstActor::MultiplyMyFloat(float Multiplier)
{
    MyFloat *= Multiplier;
    UE_LOG(LogTemp, Warning, TEXT("MyFloat is now: %f"), MyFloat);
}

코드를 추가한 후

Visual Studio에서 F7키를 눌러 프로젝트를 빌드합니다.
빌드가 완료되면 언리얼 에디터로 돌아가 Ctrl+Alt+F11을 눌러 변경사항을 적용합니다.

.uproject 파일의 역할

.uproject 파일은 JSON 형식의 프로젝트 설정 파일로, 다음 정보를 포함합니다.

엔진 버전
프로젝트에 사용된 플러그인
모듈 정의
프로젝트 설정 등

예시

{
    "FileVersion": 3,
    "EngineAssociation": "5.1",
    "Category": "",
    "Description": "",
    "Modules": [
        {
            "Name": "MyFirstCppProject",
            "Type": "Runtime",
            "LoadingPhase": "Default"
        }
    ]
}

C++ 모듈 구조

언리얼 엔진의 C++ 프로젝트는 모듈 구조를 가집니다.

각 모듈은 다음 요소로 구성됩니다.

모듈 정의 파일 (예 : MyFirstCppProject.cpp)
모듈 헤더 파일 (예 : MyFirstCppProject.h)
빌드 설정 파일 (예 : MyFirstCppProject.Build.cs)

MyFirstCppProject.Build.cs 예시

using UnrealBuildTool;
 
public class MyFirstCppProject : ModuleRules
{
    public MyFirstCppProject(ReadOnlyTargetRules Target) : base(Target)
    {
        PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;
    
        PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore" });
 
        PrivateDependencyModuleNames.AddRange(new string[] {  });
    }
}

언리얼 헤더 파일의 특징

언리얼 엔진은 자체 헤더 도구(Unreal Header Tool, UHT)를 사용하여 리플렉션 및 직렬화 코드를 생성합니다.

이를 위해 특별한 매크로와 구문을 사용합니다.

##pragma once : 헤더 가드로 사용됩니다.
##include "CoreMinimal.h" : 자주 사용되는 언리얼 엔진 타입들을 포함합니다.
UCLASS(), UPROPERTY(), UFUNCTION() 등의 매크로
GENERATED_BODY() 매크로

흔한 문제점과 해결 방법

1. 문제 : 빌드 오류 - "error C1083: Cannot open include file: '*.generated.h': No such file or directory"

해결: 프로젝트를 다시 생성하거나, 언리얼 헤더 도구를 수동으로 실행합니다.

2. 문제 : 인텔리센스 오류 (빨간 밑줄)가 있지만 빌드는 성공하는 경우

해결 : Visual Studio를 재시작하거나, 프로젝트 캐시를 삭제합니다.

3. 문제 : 새로 추가한 클래스가 언리얼 에디터에 나타나지 않음

해결 : 에디터에서 Ctrl+Alt+F11을 눌러 변경사항을 적용하거나, 에디터를 재시작합니다.

효율적인 프로젝트 구조 설계 팁

논리적인 폴더 구조 사용 : Source 폴더 내에서 기능별로 하위 폴더를 만들어 코드를 구성합니다.
명확한 명명 규칙 적용 : 언리얼 엔진의 명명 규칙을 따라 일관성 있게 클래스와 변수의 이름을 지정합니다.
인터페이스 활용 : UINTERFACE와 IInterface를 사용하여 코드의 결합도를 낮추고 유연성을 높입니다.
모듈화 : 기능별로 별도의 모듈을 만들어 코드를 분리하고 재사용성을 높입니다.
프리컴파일드 헤더 사용 : 빌드 시간을 단축시키기 위해 프리컴파일드 헤더를 적극 활용합니다.

이러한 단계와 팁을 따라 첫 번째 언리얼 C++ 프로젝트를 성공적으로 생성하고 구조를 이해할 수 있습니다.

프로젝트의 규모와 복잡성이 증가함에 따라 이러한 기본 구조를 기반으로 확장해 나갈 수 있습니다.

이전으로 다음으로