첫 번째 C++ 프로젝트 생성

개발 환경 설정에서 엔진과 Visual Studio를 설치했다면, 이제 실제로 C++ 코드를 담을 프로젝트를 만들 차례입니다. 처음 만드는 프로젝트는 기능이 거의 없는 빈 프로젝트가 좋습니다. 아무 코드도 추가하지 않은 상태에서 먼저 빌드해 두면, 나중에 오류가 났을 때 그것이 내가 추가한 코드의 문제인지 도구 환경의 문제인지를 나눌 수 있기 때문입니다.

이 글에서는 프로젝트 브라우저에서 Blank C++ 프로젝트를 만들고, 생성된 파일이 각각 무슨 일을 하는지 살펴본 뒤, Visual Studio에서 첫 빌드를 해 봅니다. 프로젝트 브라우저의 옵션 이름과 시작 레벨의 모습은 엔진 버전과 템플릿에 따라 다를 수 있으며, 이 글은 언리얼 엔진 5.8을 기준으로 합니다.

---

프로젝트 브라우저 열기

Epic Games Launcher를 실행하고 Unreal Engine 탭에서 설치한 엔진 버전 옆의 실행(Launch) 버튼을 누르면 언리얼 에디터가 시작됩니다. 에디터가 열리기 전에 먼저 프로젝트 브라우저(Project Browser)가 나타나는데, 여기서 기존 프로젝트를 열거나 새 프로젝트를 만들 수 있습니다. 이번에는 새 프로젝트를 만듭니다.

---

템플릿 고르기

프로젝트 브라우저 왼쪽에는 게임(Games), 영화·TV·라이브 이벤트, 건축·엔지니어링·건설, 자동차·제품 디자인·제조 같은 개발 범주가 있고, 각 범주에는 여러 프로젝트 템플릿이 있습니다. 템플릿은 특정 장르나 목적에 맞춰 기본 에셋과 설정을 미리 담아 둔 출발점입니다.

이 교재는 게임 개발을 목표로 하므로 게임 범주를 고르고, 그 안에서 블랭크(Blank) 템플릿을 선택합니다. 블랭크는 최소한의 구성 요소만 담은 가장 기본적인 템플릿이라, 필요 없는 캐릭터나 입력 설정 없이 처음부터 C++ 코드를 작성하기에 알맞습니다.

---

프로젝트 기본 설정 정하기

블랭크 템플릿을 고르면 오른쪽에 프로젝트 기본 설정(Project Defaults)이 나타납니다. C++ 프로젝트를 만들 때 실수가 가장 잦은 곳이 여기입니다.

가장 먼저 구현 방식을 블루프린트(Blueprint)와 C++ 가운데 고르는데, 이 실습에서는 C++를 선택합니다. 블루프린트 프로젝트에도 나중에 C++ 클래스를 추가할 수 있지만, 여기서는 처음부터 C++ 모듈을 갖춘 구성으로 시작합니다. 대상 플랫폼(Target Platform)은 데스크톱(Desktop)과 모바일(Mobile) 가운데 고르며, PC에서 학습한다면 데스크톱을 고릅니다.

품질 프리셋(Quality Preset)은 렌더링 품질 설정으로, 최대(Maximum)와 확장 가능(Scalable) 가운데 고릅니다. Epic의 문서는 PC나 콘솔에는 Maximum을, 모바일 기기에는 Scalable을 권장합니다. 학습 단계에서는 시각 옵션을 확인하기 쉬운 Maximum으로 시작하고, 성능을 확인하는 것이 목적이라면 Scalable로 바꿔 볼 수 있습니다.

시작 콘텐츠(Starter Content)는 기본 메시, 머티리얼, 텍스처 같은 에셋을 프로젝트에 넣을지 정하는 옵션입니다. 필수는 아니지만, 아무 에셋도 없는 빈 공간보다 몇 가지 물체를 배치해 볼 수 있는 환경이 학습 초기에는 편합니다. 레이 트레이싱(Ray Tracing)은 지원하는 그래픽 카드에서 실시간 레이 트레이싱을 쓸지 정하는 옵션입니다. 대상 하드웨어와 렌더링 목표에 맞춰 고르면 되고, 이 글의 C++ 프로젝트 생성에는 필요하지 않으므로 꺼 두어도 됩니다.

프로젝트 이름에는 MyFirstCPPProject처럼 간단하고 뜻이 분명한 이름을 씁니다. 프로젝트 이름은 C++ 모듈 이름과 클래스 이름에도 쓰이므로 영문자로 시작하고, 공백이나 특수 문자는 피하는 것이 좋습니다. 프로젝트 위치(Project Location)는 기본 경로를 그대로 써도 되고 원하는 폴더를 지정해도 되는데, SSD에 두면 빌드와 로딩이 빠릅니다. 설정을 모두 마쳤으면 오른쪽 아래의 생성(Create) 버튼을 누릅니다.

---

생성된 파일과 Visual Studio

생성 버튼을 누르면 언리얼 엔진이 프로젝트 폴더를 만들고 필요한 파일을 준비합니다. 이때 Visual Studio에서 프로젝트를 열기 위한 솔루션 파일(.sln)도 함께 생성되고, 설정에 따라 Visual Studio가 자동으로 실행되기도 합니다. Visual Studio 2026을 쓰는 환경에서는 새 솔루션 형식인 .slnx 파일이 함께 있을 수 있으며, 언리얼 엔진 5.8.4부터 에디터는 두 파일이 모두 있으면 .slnx를 엽니다. Visual Studio가 자동으로 열리지 않았다면 프로젝트 폴더로 가서 MyFirstCPPProject.sln(또는 .slnx)을 직접 더블클릭해 엽니다.

Visual Studio의 솔루션 탐색기(Solution Explorer)를 보면 방금 만든 프로젝트의 파일 구조를 확인할 수 있습니다. Source 폴더 아래에 프로젝트 이름과 같은 폴더(MyFirstCPPProject)가 있고, 그 안에 헤더 파일(.h)과 소스 파일(.cpp)이 있습니다. 프로젝트를 이루는 파일은 하는 일에 따라 다음처럼 나눌 수 있습니다.

이 가운데 .sln은 엔진이 다시 만들어 낼 수 있는 파일이라는 점이 다른 파일과 다릅니다. 프로젝트의 실제 정보는 .uproject와 Source 폴더에 있으므로, 솔루션 파일이 꼬이면 .uproject를 마우스 오른쪽 버튼으로 눌러 Visual Studio 프로젝트 파일을 다시 생성할 수 있습니다.

---

첫 빌드와 실행 확인

프로젝트를 만들고 나면 언리얼 에디터와 Visual Studio가 모두 열려 있을 것입니다. 에디터에는 선택한 템플릿의 시작 레벨이 열리는데, 기본 조명이나 바닥 같은 구성은 버전과 템플릿에 따라 다르므로 화면이 완전히 비어 있어야 하는 것은 아닙니다. Visual Studio에는 프로젝트 솔루션이 열려 있고, MyFirstCPPProject.Build.cs, MyFirstCPPProject.h, MyFirstCPPProject.cpp 같은 파일이 보입니다. 이 파일들이 게임 모듈의 초기 구조를 정합니다.

다음 글로 넘어가기 전에 세 가지를 차례로 확인합니다. 먼저 에디터와 IDE가 같은 프로젝트 경로와 같은 엔진 버전을 쓰고 있는지 봅니다. 그다음 Visual Studio의 솔루션 구성에서 Development Editor(표기에 따라 DevelopmentEditor)를, 플랫폼에서 Win64를 고르고, 솔루션 탐색기의 게임 프로젝트 MyFirstCPPProject를 선택해 Build를 실행한 뒤, Build Output에서 성공했는지 또는 첫 오류가 무엇인지 확인합니다. 마지막으로 그 프로젝트를 에디터에서 열고 Play를 시작했다가 멈출 수 있는지 확인합니다.

여기서 Editor 타깃을 고르는 이유는 에디터가 불러올 게임 모듈을 만들기 위해서입니다. 이름이 비슷한 Development 구성은 에디터 없이 실행하는 게임(Game) 타깃이므로, 에디터에서 쓸 코드를 빌드할 때와는 구별해야 합니다. 빌드 구성의 이름은 [구성][타깃 종류] 형식이라서, DevelopmentEditor는 Development 구성의 Editor 타깃이라는 뜻입니다.

처음 만든 Blank 프로젝트를 아무것도 추가하지 않은 채 먼저 빌드하는 것도 같은 이유입니다. 빌드 대상과 프로젝트 경로, 엔진 버전을 기록해 두고 MyFirstCPPProject.uproject를 같은 엔진으로 다시 열어 봅니다. 첫 빌드가 성공하기 전에는 새 기능을 여러 개 추가하지 않으며, 빌드 로그에 SDK 누락이나 C++ 오류가 있으면 그 첫 원인부터 해결합니다. 새 클래스를 배치하고 동작을 확인하는 일은 다음 장에서 이어 갑니다.

---

정리

• 프로젝트 브라우저에서 게임 범주의 Blank 템플릿을 고르고, 프로젝트 기본 설정에서 C++를 선택해야 처음부터 C++ 모듈을 갖춘 프로젝트가 만들어집니다.
• 품질 프리셋은 Maximum과 Scalable 가운데 고르며, 시작 콘텐츠와 레이 트레이싱은 C++ 빌드에 필요하지 않은 선택 사항입니다.
• .uproject는 프로젝트 정보, Source는 C++ 코드, .Build.cs는 모듈 빌드 규칙, .sln(또는 .slnx)은 IDE용 솔루션 파일입니다. 솔루션 파일은 .uproject에서 다시 생성할 수 있습니다.
• 에디터에서 쓸 코드는 Development Editor 구성과 Win64 플랫폼으로 빌드하며, Development 구성은 에디터 없는 게임 타깃입니다.
• 아무것도 추가하지 않은 프로젝트를 먼저 빌드해 두면, 이후의 오류가 추가한 코드 때문인지 도구 환경 때문인지 나눌 수 있습니다.

---

연습 문제

1. 자동 완성은 되는데 빌드는 실패하면

MyFirstCPPProject.sln이 열렸고 헤더 파일에서 자동 완성도 잘 표시되지만, Editor 타깃 Build는 실패했습니다. .sln, .Build.cs, .uproject는 각각 어떤 역할을 할까요? 지금 새 클래스가 에디터에 반영되었다고 말할 수 있을까요?

해설 보기

.sln은 IDE가 프로젝트를 열기 위한 구성이고, .Build.cs는 게임 모듈의 빌드 규칙이며, .uproject는 사용할 엔진과 프로젝트 모듈 같은 프로젝트 정보를 연결합니다.

IDE가 열리고 자동 완성이 되는 것은 편집할 수 있다는 뜻일 뿐, Editor 타깃 빌드가 성공했다는 뜻은 아닙니다. 빌드가 실패했으므로 새 클래스는 아직 에디터에 반영되지 않았습니다. 먼저 Build Output의 첫 오류를 해결하고, 같은 프로젝트를 에디터에서 열어 모듈이 반영되었는지 확인해야 합니다.

2. 빌드 구성 고르기

에디터에서 쓸 C++ 클래스를 고친 뒤, 솔루션 구성을 Development로 두고 빌드했더니 성공했습니다. 그런데 에디터에는 바뀐 내용이 보이지 않습니다. 무엇이 문제일까요?

해설 보기

Development는 에디터 없이 실행하는 Game 타깃의 구성이므로, 에디터가 불러오는 모듈은 다시 빌드되지 않았습니다. 빌드 구성 이름은 [구성][타깃 종류] 형식이라, 에디터용 모듈을 만들려면 Development Editor 구성을 골라야 합니다.

구성을 Development Editor, 플랫폼을 Win64로 바꾸고 게임 프로젝트를 다시 빌드한 뒤 에디터에서 결과를 확인합니다.

빌드 구성과 타깃의 종류는 Epic의 C++ 게임 프로젝트 컴파일 문서에서, 프로젝트 브라우저의 옵션은 새 프로젝트 만들기 문서에서 확인할 수 있습니다. 도구의 버전은 앞 글에서 본 엔진별 호환 표를 따릅니다.

다음 글 언리얼 에디터와 주요 패널 이해에서는 레벨 에디터의 주요 패널을 살펴보고, C++ 클래스가 에디터의 어디에 나타나는지 확인합니다.