언리얼 엔진 5 C++ 개발(WIL)

• 언리얼 엔진 5 C++ 개발 환경 설정 요약

1. 언리얼 엔진 5 설치 및 설정
Epic Games Launcher 설치 및 실행 → "언리얼 엔진" 탭 → "라이브러리" 에서 버전 확인
각 버전마다 내부 코드 구조와 빌드 방식이 변경, 개선되어 버전확인 필요

5.5 버전 C++ 빌드 오류 예방을 위해 엔진 폴더(예: C:\Program Files\Epic Games\UE_5.5)의 "읽기 전용" 해제
UE_5.5\Engine 폴더 우클릭 → 속성 선택 → 읽기 전용 해제 → 하위 폴더 및 파일에도 적용
엔진 빌드 과정에서 폴더가 읽기 전용이면 빌드 중 파일 수정이 불가능해 컴파일 충돌이 발생할  수 있음

2. Visual Studio 2022 설치 및 설정
Visual Studio Installer 실행 → Visual Studio 2022 Community 확인 및 업데이트

언리얼 필수 워크로드
(C++를 사용한 데스크톱 개발, C++을 사용한 게임 개발)

3. C++ 프로젝트 생성
언리얼 엔진 실행 → "Games" → "Blank" 선택으로 프로젝트 생성
Project Defaults에서 C++ 선택, 사양에 따라 낮으면 Scalable, 충분 시 Maximum / Starter Content 체크 해제
프로젝트명 지정 후 저장 경로 설정 후 "Create" (한글, 특수문자, 공백은 엄금)

4. C++ 프로젝트와 Visual Studio 연동
Edit → Editor Preferences → Source Code → Source Code Editor → "Visual Studio 2022"로 설정
언리얼 에디터에서 Tools → "Open Visual Studio 2022" 클릭해 코드 편집

5. 프로젝트 폴더 구조
Epic Games Launcher의 라이브러리 탭 이동
내 프로젝트의 프로젝트 항목 우클릭 후 폴더 보기

주요 파일:
Project.sln → Visual Studio 솔루션 파일
Project.uproject → 언리얼 프로젝트 설정 파일
.vsconfig → Visual Studio 필수 워크로드, 구성요소 감지

주요 폴더:
.vs 폴더 → Visual Studio 설정 및 디버깅 정보 저장
Binaries → 빌드된 실행 파일 (.exe, .dll) 저장
Config → 게임 설정 파일 (.ini), 엔진 및 키 설정 포함
Content → 게임 에셋 (텍스처, 사운드, 애니메이션 등) 저장
DerivedDataCache → 성능 최적화를 위한 캐시 데이터
Intermediate → 컴파일 시 생성되는 임시 파일
Saved → 자동 저장, 로그, 크래시 덤프 저장 (디버깅에 활용)
Source → C++ 소스 코드 (.cpp, .h)가 들어 있는 핵심 폴더

• 언리얼 엔진 C++ 빌드 프로세스

    1. Solution Explorer 및 프로젝트 구조
Visual Strudio 내 Solution Explorer에서 프로젝트 폴더 구조 확인 (실제 디렉터리 구조와 다를 수 있음).

주요 폴더:
Engine – 언리얼 엔진 소스 (초급 단계에서 수정 X).
Games – 게임 프로젝트 코드 (Source, Config, .uproject 포함).
Programs, Rules, Visualizers – 엔진 관련 파일 및 빌드 설정 포함.

프로젝트 루트 폴더:
Games 폴더 안에 있는 프로젝트 폴더 (Project)
이 폴더가 프로젝트 루트로 게임 개발에 필요한 모든 리소스와 설정 파일이 포함됨

주요 폴더 및 파일:
Config 폴더 → 게임과 에디터의 초기 설정 저장 (.ini 파일)
DefaultEditor.ini → 에디터 환경 설정 (뷰포트, UI 등)
DefaultEngine.ini → 엔진 전반 설정 (렌더링, 네트워킹 등)
DefaultGame.ini → 게임플레이 설정 (게임 모드, 플레이어 컨트롤러 클래스 등)
DefaultInput.ini → 기본 입력 바인딩

Source 폴더 → C++ 소스 코드 및 빌드 설정 파일(.cpp, .h)
프로젝트명.Build.cs → 모듈, 라이브러리, 종속성 정의
프로젝트명.Target.cs & 프로젝트명Editor.Target.cs → 게임/에디터용 빌드 방식 정의
프로젝트명.uproject → 언리얼 에디터에서 프로젝트를 직접 실행할 때 사용

    2. C++ 빌드 설정 이해
C++ 코드 빌드 목적: C++ 코드 → 컴파일 & 링크 → DLL 생성 → 언리얼 에디터에서 로드.

 

빌드 구성 (Configuration)
DebugGame – 게임 로직만 디버그 가능.
DebugGame Editor – 에디터에서 디버깅 가능.
Development – 최적화된 개발용 빌드.
Development Editor – 가장 많이 사용됨 (테스트 및 Live Coding과 궁합 좋음).
Shipping – 최종 배포용 빌드 (최적화 극대화).
플랫폼: 기본 Win64 (기타 플랫폼 빌드는 추가 SDK 필요).

    3. Visual Studio에서 빌드 및 실행
전체 빌드 (Ctrl + Shift + B) – 모든 모듈 빌드 (시간 오래 걸림).
부분 빌드 (Solution Explorer에서 프로젝트 우클릭 → Build) – 게임 코드만 빌드.
빌드 후 실행:
Set as Startup Project → F5 (Start Debugging)로 실행.
종료 시 Shift + F5.

    4. Live Coding 활용 (빠른 코드 반영)
Live Coding 활성화 (에디터 하단 Live Coding 아이콘 클릭).
적용 가능: 함수 내부 변경, 변수 값 수정 등.
적용 불가: UCLASS, USTRUCT, UENUM 변경, 새로운 클래스 추가 등 (이 경우 전통적인 빌드 필요).

    5. 빌드 문제 해결 (변경 사항 미반영 시)
언리얼 에디터 & Visual Studio 종료.
Intermediate, DerivedDataCache, Saved 폴더 삭제 (빌드 캐시 초기화).
.uproject → "Generate Visual Studio project files" 실행.
Visual Studio에서 Clean Solution 후 다시 빌드.
에디터 재실행 후 코드 반영 확인.
:point_right: 정상 빌드 후 "Build completed" 메시지 확인, DLL이 Binaries/Win64 폴더에 생성됨.

• 아트 리소스 셋업

    1. 프로젝트 다운로드 및 리소스 추가

리소스 프로젝트 다운로드 후 압축 해제 → 언리얼 프로젝트 폴더에 배치

언리얼 에디터 종료 후 Epic Games Launcher 재실행 → 리소스 프로젝트 오픈

Content Browser에서 Resources 폴더 우클릭 → Migrate 선택

메인 프로젝트의 Content 폴더를 경로로 지정 후 Migrate 완료

 

    2. 새 레벨 생성 및 기본 레벨 설정

Content 폴더 아래 Maps 폴더 생성

File → New Level → Basic 선택 후 MainLevel로 저장

Edit → Project Settings → Maps & Modes

Editor Startup Map, Game Default Map을 MainLevel로 지정

 

    3. UObject vs. AActor 이해

UObject: 월드에 배치 X, 데이터/로직 관리

AActor: 월드에 배치 O, 위치/회전/크기 및 컴포넌트 추가 가능

 

    4. 새 Actor 클래스 생성 및 배치

Tools → New C++ Class → Actor 선택 → 클래스명 Item 생성

생성된 Item.h, Item.cpp 확인 후 빌드 완료 & Reload All

언리얼 에디터 Content Browser에서 Item을 레벨 뷰포트에 배치

Outliner 창에서 Item 확인

 

    5. Actor 클래스 삭제 방법

Visual Studio에서 .h, .cpp 파일 Remove

윈도우 내 프로젝트 폴더에서 직접 삭제 (Public/Private 폴더)

빌드 후 언리얼 에디터 재실행

에디터 종료 → Remove → 물리 파일 삭제 → 빌드 → 재실행 순서 필수!

• 언리얼 엔진 Actor 클래스 구조

    1. Actor 클래스의 기본 구조 (Item.h, Item.cpp)

헤더 파일 (Item.h) 주요 요소:

#pragma once

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

UCLASS()
class PROJECT_API AItem : public AActor
{
		GENERATED_BODY()
	
public:
		AItem();

protected:
		virtual void BeginPlay() override;
		virtual void Tick(float DeltaTime) override;
};

 

#pragma once: 중복 포함 방지

 

#include "CoreMinimal.h": 기본 타입과 매크로 포함

#include "GameFramework/Actor.h": AActor 상속을 위해 필요

#include "Item.generated.h": 리플렉션 시스템 자동 생성 매크로

 

UCLASS(), GENERATED_BODY()  → 리플렉션 시스템 인식 매크로

class PROJECT_API AItem : public AActor

AActor 상속 → AItem 클래스 정의

AItem →  [A(Actor), U(Object), F(일반 구조체), T(템플릿), E(열거형)]

PROJECT_API → 모듈 외부에서 접근 가능하도록 지정

 

라이프사이클 관련 함수

AItem() → 생성자 (메모리에 생성될 때 호출)

BeginPlay() → 월드에 배치 후 한 번 실행

Tick(float DeltaTime) → 매 프레임마다 실행

 

구현 파일 (Item.cpp) 주요 요소:

#include "Item.h"


AItem::AItem()
{
		PrimaryActorTick.bCanEverTick = true;
}

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

void AItem::Tick(float DeltaTime)
{
		Super::Tick(DeltaTime);
}

 

#include "Item.h": 짝이 되는 헤더 파일 포함

PrimaryActorTick.bCanEverTick = true; → Tick() 실행 여부 설정

라이프사이클 함수 (BeginPlay(), Tick())

Super::BeginPlay();, Super::Tick(DeltaTime); → 부모 클래스 로직 유지

 

2. Actor 클래스에 컴포넌트 추가 및 초기화

① 컴포넌트 개념

• 컴포넌트: 액터의 기능을 추가하는 부품
• 루트 컴포넌트 (Root Component)
• 모든 액터는 하나의 루트 컴포넌트를 가져야 함\
• USceneComponent → 위치, 회전, 크기 관리
• Static Mesh Component (UStaticMeshComponent)
• 3D 모델을 화면에 표시하는 역할