Visual Studio C++ 솔루션 구조 이해하기

1️⃣ Visual Studio에서 Solution Explorer 확인

• Visual Studio를 실행하고, 좌/우측 패널에 있는 Solution Explorer 창을 열어보자.

• 여기서 프로젝트 폴더들이 계층적으로 표시되는데, 실제 Windows 탐색기에서 보았던 프로젝트 폴더 구조와는 조금 다를 수 있다.
  

• Visual Studio는 빌드와 관리를 용이하게 하기 위해 디스크의 실제 폴더 구조와는 별개로 "가상 폴더 구조"를 생성한다.

• 따라서 Windows 탐색기의 실제 폴더 구조와 1:1로 대응되지 않을 수 있음을 유의해야 한다. 빌드 규칙이나 엔진 소스 파일은 가상 폴더 구조에서 위치가 다르게 보이더라도, 실제로는 엔진 설치 폴더와 프로젝트 폴더에 그대로 존재한다.

2️⃣ 솔루션 구조 내 주요 폴더

• Engine 폴더

  • 언리얼 엔진 자체 소스 코드와 리소스가 담긴 곳이다.
  • 에디터 작동, 엔진 코어 관련 코드가 포함되어 있지만, 초급 단계에서는 거의 수정할 일이 없습니다.

• Games 폴더 (중요!)

  • 우리가 만든 프로젝트 코드가 모두 들어 있다.
  • 내부에는 Source, Config, .uproject 파일 등이 있으며, C++로 작성하는 게임 로직을 이 폴더에서 가장 많이 다루게 된다.
    

• Programs 폴더

  • 엔진 동작에 필요한 유틸리티 프로그램이나 서버 모듈이 담겨 있다.
  • 초급 단계에서는 거의 볼 일이 없다.

• Rules 폴더

  • 엔진과 게임 등 각 모듈의 빌드 규칙을 정의해 놓은 파일들이 모여 있다.
  • 모듈 의존성, 플러그인 활성화 여부, 빌드 대상 등을 제어한다.

• Visualizers 폴더

  • Visual Studio에서 디버깅 시 언리얼 엔진 관련 자료구조를 보기 좋게 표시하기 위한 설정 파일이 들어 있다.

3️⃣ 프로젝트 루트 폴더 (Games/프로젝트명)

• Games 폴더 안을 열어보면, 여러분이 만든 프로젝트 이름(SpartaProject)이 보인다.
• 이 폴더가 “프로젝트 루트”이며, 게임 개발에 필요한 모든 리소스와 설정 파일이 이곳에 모여 있다.

4️⃣ 프로젝트 루트 폴더 주요 구성 요소

• Config 폴더

  • .ini 파일을 통해 에디터와 게임의 초기 상태를 지정한다.
    - DefaultEditor.ini: 에디터 환경 설정 (뷰포트, UI 등)
    - DefaultEngine.ini: 엔진 전반 설정 (렌더링, 네트워킹 등)
    - DefaultGame.ini: 게임플레이 관련 설정 (게임 모드, 플레이어 컨트롤러 클래스 등)
    - DefaultInput.ini: 키보드·마우스·패드 등의 기본 입력 바인딩
    

• Source 폴더

  • 실제 C++ 소스 코드(.cpp, .h)가 들어 있다.
  • 최초 프로젝트 생성 시에는 프로젝트명.cpp, 프로젝트명.h 등 최소 파일만 있지만, 새 클래스를 만들수록 점차 늘어난다.
  • 빌드 설정 관련 주요 파일도 포함된다.
    - 프로젝트명.Build.cs: 해당 프로젝트에 필요한 모듈, 라이브러리, 종속성 등을 정의
    - 프로젝트명.Target.cs, 프로젝트명Editor.Target.cs: 각각 게임 실행용, 에디터용 빌드 방식을 정의
    

• 프로젝트명.uproject
  - 언리얼 에디터에서 이 파일을 열면 프로젝트를 직접 실행할 수 있다.
  - 에디터는 이 파일을 통해 “어떤 콘텐츠와 설정을 불러올지”를 판단한다.
  

Visual Studio C++ 빌드 설정 이해하기

1️⃣ C++ 코드 빌드의 목적

• C++ 코드를 수정했다면, 이를 컴파일(Compile) + 링크(Link) 해 “동적 라이브러리 (DLL)”로 만들어야 한다.

  C 파일 수정 -> 빌드 (컴파일 + 링크) -> DLL 파일 -> 언리얼 에디터

• 그렇게 생성된 DLL이 언리얼 에디터에서 로드되어, 새로 작성한 로직 (함수, 클래스 등)이 게임이나 에디터 내에서 즉시 반영된다.

2️⃣ 빌드 구성 및 플랫폼 확인

• Visual Studio 상단 툴바에는 빌드 구성 (Configuration)과 플랫폼 (Platform)을 선택하는 드롭다운이 있다.
  • 왼쪽 - 빌드 구성 (예: DebugGame, Development Editor 등)
  • 오른쪽 - 플랫폼 (Win64)

• 빌드 구성 (Configuration) 종류
  • DebugGame
    • 게임 로직만 디버그 정보를 포함하고, 엔진은 최적화된 상태로 빌드한다.
    • 에디터가 아닌 독립 실행 파일 환경에서 디버깅이 가능하다.
  • DebugGame Editor
    • 에디터 환경에서 게임 로직을 디버그하기 편한 설정이다.
    • 에디터 플레이 중에 C++ 로직을 추적하거나 브레이크포인트를 걸어볼 수 있다.
  • Development
    • 디버그 정보를 최소화해 실행 속도를 높인 개발용 빌드다.
    • 독립 실행 파일 환경 테스트·개발 단계에서 주로 쓰인다.
  • Development Editor
    • 에디터에서도 개발·테스트를 원활히 할 수 있도록 구성된 빌드 모드다.
    • Live Coding 사용 시나리오와 궁합이 좋고, 초·중급자들이 자주 사용한다.
    • 본 강의에서도 기본 모드로 활용한다.
  • Shipping
    • 최종 사용자에게 배포할 때 사용하는 릴리스 빌드이다.
    • 디버그 정보를 제거하고, 성능 최적화가 극대화된다.
• 플랫폼 (Platform) 설정
  • 기본적으로 Win64가 선택되어 있으며, 이는 Windows 64비트 환경을 의미.
  • 모바일 (Android, iOS), 콘솔 (PS, Xbox 등)로 빌드하려면 해당 플랫폼용 SDK를 추가로 설치해야 한다.

Visual Studio에서 C++ 빌드하기

1️⃣ 전체 솔루션 빌드 vs. 부분 빌드

• 언리얼 C++ 프로젝트는 “전체 솔루션 빌드”와 “부분 빌드”로 나누어 빌드할 수 있다.
• 전체 솔루션 빌드
• Visual Studio 메뉴 Build → Build Solution (단축키: Ctrl + Shift + B)
  • 엔진, 유틸리티, 게임 등 모든 모듈을 통째로 빌드한다.
  • 첫 빌드나 엔진 소스를 수정했을 때, 또는 엔진 전체 파일이 필요한 경우에 사용한다.
  • 프로젝트 규모가 크면 시간이 오래 걸릴 수 있다.

• 부분 빌드
  • Solution Explorer에서 프로젝트 (예: SpartaProject)를 우클릭 → Build 선택
  • 엔진이나 다른 모듈을 제외하고, 게임 프로젝트 코드만 빠르게 빌드한다.
  • 일반적으로 C++ 로직만 수정했다면 이 방법을 쓰는 것이 효율이다.
    

2️⃣ 빌드 전후 체크 포인트

• 빌드 시작 전
  • 언리얼 에디터는 가급적 종료하고 빌드하는 편이 안전합니다.
  • 에디터가 실행 중이면 수정된 DLL을 교체하지 못해 빌드 에러가 발생할 수 있습니다.
• 빌드 진행
  • Visual Studio 하단 Output 창에서 빌드 메시지를 모니터링해라.
  • Output 창 우측 상단을 Build Only로 변경합니다. 그래야만 빌드 문제만을 우선적으로 확인할 수 있다.
  • “처음 빌드”는 엔진 모듈까지 모두 새로 컴파일하므로 오래 걸릴 수 있지만, 이후에는 변경된 소스만 컴파일해서 빌드 시간이 크게 단축된다.
  • 경고 (Warning)나 에러 (Error)가 뜨면 Error List 창에서 구체적인 원인을 확인할 수 있다.
    
• 빌드 결과
  • “Build completed” 메시지가 나오면 정상 빌드된 것이다.
    
  • 빌드 후, 프로젝트 폴더의 Binaries/Win64 폴더 내에 UnrealEditor-프로젝트명.dll 등이 새로 생성됩니다.
    
  • 이제 언리얼 에디터를 실행하면, 이 DLL을 로드해 수정된 로직이 적용됩니다.

3️⃣ 빌드 후 실행 대상 설정

• Solution Explorer에서 UE5 프로젝트 (SpartaProject)를 우클릭하고, Set as Startup Project를 선택하자.
  
  • 이렇게 하면, 디버깅 시 실행될 기본 프로젝트로 설정된다.
  • UE5 에디터와 함께 실행하거나, Visual Studio의 디버깅 도구를 사용할 때 편리하다.
• 이후 F5 (Start Debugging) 또는 Debug → Start Debugging을 선택해 UE5 에디터를 실행할 수 있다.
• 디버깅 실행 상태를 종료하고 싶다면, 언리얼 에디터 상에서 종료를 하거나, Visual Studio에서 Shift + F5를 누르면 에디터가 종료된다.

언리얼 에디터에서 Live Coding 실행하기

1️⃣ 기존 빌드 흐름 vs. Live Coding

• 기존 방식
  • “Shift + F5 (에디터 연결 종료) → C++ 코드 수정 → Visual Studio에서 빌드 → F5 (에디터 재연결) → 결과 확인”
• Live Coding 활용 시
  • “(에디터 연결 종료 안한채) C++ 코드 수정 → Live Coding으로 변경 사항만 컴파일 → 에디터에 즉시 로직 반영”
• Live Coding을 사용하면 에디터를 일일이 끄고 켜는 번거로움이 줄어든다.

2️⃣ Live Coding 제약사항

• 간단한 코드 변경: 함수 내부 로직, 변수 값 변경, 로그 출력 변경 등은 Live Coding으로 즉시 반영된다.
• 적용이 안 되는 경우
  • UCLASS, USTRUCT, UENUM 매크로의 추가·삭제·수정
  • 새로운 C++ 클래스 (.h/.cpp) 생성
  • 엔진 코어 영역 수정
  • 함수 시그니처 (인자, 반환값)나 클래스 상속 구조 변경
• 이 경우에는 전통적인 빌드 프로세스 (에디터 종료 → Visual Studio 빌드 → 에디터 재실행)가 필요하다.

3️⃣ Live Coding 기능 활성화

• 언리얼 에디터 하단의 Live Coding 아이콘 (벽돌 모양) 옆 세로 점 3개(… 메뉴)에서 Enable Live Coding을 체크하자.
  

4️⃣ Live Coding 사용 방법

• Visual Studio에서 코드를 수정 후, Ctrl + Shift + S (또는 상단 메뉴에서 File → Save All)로 모든 파일을 저장한다.
• 에디터 창 하단에 있는 Live Coding 아이콘을 클릭하거나, 단축키 Ctrl + Alt + F11을 눌러 Live Coding 빌드를 시작한다.
• 컴파일이 완료되면 Live Coding 창에 “Finished” 메시지가 뜨고, 에디터가 즉시 수정된 로직을 반영한다.

빌드 문제 복구하기

1️⃣ 변경 사항 미반영 문제란?

• C++ 코드를 수정하고 빌드를 완료 하였음에도 불구하고, 언리얼 에디터에서 반영이 안 되는 경우가 있다.
• 빌드 캐시나 프로젝트 설정 문제, 혹은 파일 경로가 꼬여서 발생할 수 있으며, 아래와 같은 형태로 나타난다.
  • 컴파일 대상 누락: Visual Studio 혹은 엔진이 수정된 소스를 인식 못 해 빌드 대상에서 누락됨
  • DLL 교체 문제: 빌드가 끝났어도 에디터가 새 DLL을 로드하지 못함
  • 캐시 문제: 이전 빌드 결과물이 남아 새 빌드 결과를 덮어씌우지 못함
  • 파일 경로 문제: 헤더 파일 경로나 플러그인 설정이 잘못되어 컴파일에 포함되지 않음

2️⃣ 단계별 해결 가이드

1. 언리얼 에디터와 Visual Studio 종료
   • 실행 중인 프로세스들이 빌드 파일을 잠글 수 있으므로, 모두 끄고 새로 시작하는 것이 좋다.
2. 프로젝트 폴더에서 Intermediate, DerivedDataCache, Saved 폴더 삭제
   • 이 폴더들은 빌드 캐시 및 임시 데이터를 담고 있다.
   • 삭제 후 다시 빌드하면 새로 생성되어, 잘못된 캐시로 인한 오류를 해결할 수 있다.
3. .uproject 파일을 우클릭 → “Generate Visual Studio project files”
   • 솔루션(.sln) 파일과 프로젝트 설정을 재생성하여, 누락되었거나 꼬인 구성을 복구한다.
4. Visual Studio에서 클린 빌드
   • 새로 생성된 솔루션을 열고,
     • Build → Clean Solution으로 기존 빌드 산출물을 정리
     • Build → Build Solution으로 프로젝트 재빌드
   • 에러가 난다면 Output 창과 Error List를 확인해 원인을 파악하고 수정한다.
5. 언리얼 에디터 다시 실행
   • 에디터를 다시 실행해 코드 변경 사항이 반영되었는지 확인한다.
   • 여전히 문제가 계속된다면,
     • Saved/Logs 폴더의 로그를 확인해 구체적인 에러를 찾고,
     • 엔진 버전이나 프로젝트 설정을 점검해 보자.