게임 프로젝트에도 UE Public/Private 구조가 필요할까?

Unreal C++ 모듈에서 Public과 Private은 파일 공개 범위를 나누기 위한 구조이다.

Source/MyGame/
  Public/
    Player/
      MyPlayerController.h

  Private/
    Player/
      MyPlayerController.cpp

Public:

• 다른 모듈이 include해도 되는 헤더
• 외부에 공개되는 API
• 상속/참조될 수 있는 타입

Private:

• 현재 모듈 내부 구현
• 외부 모듈에서 직접 include하지 않을 헤더/cpp

#include "Player/MyPlayerController.h"

Public/Private을 쓰는 이유

장점

• 모듈 경계가 명확해진다.
• 외부에 노출되는 API가 줄어든다.
• include 의존성을 줄일 수 있다.
• 빌드 시간이 안정적이다.
• 플러그인/멀티 모듈 구조로 확장하기 쉽다.
• Rider/VS/UBT include path가 덜 꼬인다.
• ../ 상대 include를 줄일 수 있다.

단점

• 폴더 깊이가 늘어난다.
• 도메인 폴더가 한눈에 덜 보인다.
• 소규모 단일 게임 모듈에서는 과하게 느껴질 수 있다.
• 헤더와 cpp가 떨어져 있어 작업감이 불편할 수 있다.

Public/Private 없이 쓰는 경우

Source/MyGame/
  Player/
    MyPlayerController.h
    MyPlayerController.cpp
  Character/
    MyCharacter.h
    MyCharacter.cpp
  UI/

장점:

• 보기 편하다.
• 도메인별 구조가 바로 보인다.
• 헤더와 cpp가 가깝다.
• 혼자 하거나 작은 프로젝트에서는 빠르다.

단점:

• include path를 Build.cs에 직접 추가해야 할 수 있다.
• ../ 상대 include가 늘어날 수 있다.
• 모듈 경계가 흐려진다.
• 나중에 플러그인/모듈 분리할 때 정리 비용이 커진다.
• IDE 인덱싱과 UBT 해석이 다르게 보일 수 있다.

Build.cs에서 경로를 추가하면 동작하게 만들 수 있다.

PrivateIncludePaths.AddRange(new string[]
{
    "MyGame",
    "MyGame/Player",
    "MyGame/Character",
    "MyGame/UI"
});

하지만 장기적으로는 Unreal 표준 구조인 Public/Private가 더 안정적이다.

IDE 인덱싱과 UBT 해석 괴리

Rider/Visual Studio는 파일을 표시하는데 Unreal 빌드는 실패하거나, 반대로 빌드는 되는데 IDE는 빨간 줄을 띄우는 상황이 발생할 수 있다.

UBT는 실제 빌드 기준

.uproject
*.Build.cs
*.Target.cs
Source/모듈명/Public
Source/모듈명/Private
모듈 Dependency 설정
엔진 include path
플러그인 설정

UBT 기준으로 include path가 안 잡혀 있으면 실제 빌드가 실패한다.
Rider에서는 찾아지는 것처럼 보여도, Build.cs에 경로가 없고 Public/Private 표준 구조도 아니면 UBT 빌드에서 실패할 수 있음.

#include "Player/MyPlayerController.h"

IDE 인덱싱은 편집기 기준
IDE는 자체적으로 인덱싱해 추측한다.
그래서 UBT가 허용하지 않는 include도 IDE에서는 찾을 수 있음.

현재 폴더 근처에서 헤더 찾기
프로젝트 전체 파일명 검색
.sln/.vcxproj에 들어간 경로 참고
이전 캐시 참고
compile database 참고

반대로 UBT는 빌드 가능한데 IDE가 아직 프로젝트 파일/캐시를 갱신하지 못해서 빨간 줄을 띄우는 경우도 있다.

::: Title="상황 : IDE는 되는데 빌드는 안 됨", Color="Red", Alpha="0.2"

구조:

Source/MyGame/
  Player/
    MyPlayerController.h
  UI/
    MyHUD.cpp

MyHUD.cpp

#include "Player/MyPlayerController.h"

IDE는 프로젝트 안에 Player/MyPlayerController.h가 있으니까 찾아줄 수 있음.

하지만 UBT는 Source/MyGame/ 또는 Source/MyGame/Player가 include path로 등록되어 있지 않으면 빌드 실패할 수 있다.

해결:

1. Public/Private 구조로 옮기기
또는
2. Build.cs에 IncludePaths 추가

:::

::: Title="상황 : 빌드는 되는데 IDE에 빨간 줄", Color="Red", Alpha="0.2"

Build.cs를 수정해서 UBT는 경로를 아는데, IDE가 아직 갱신을 못 한 경우.

해결:

.uproject 우클릭 -> Generate Project Files
Rider에서 Refresh/Rescan
Intermediate/ProjectFiles 재생성
Rider 캐시 무효화

:::

---

IDE 인덱싱은 편집기가 코드를 읽기 위해 추측하는 경로,
UBT 해석은 실제 Unreal 빌드가 따르는 경로.

하나의 게임 프로젝트에서 Public/Private 구조의 이점

아래 상황이면 Public/Private의 의미가 커진다.

• Runtime 모듈과 Editor 모듈을 분리한다.
• UI/Combat/Online 등을 별도 모듈로 나눈다.
• 프로젝트 내부 플러그인을 만든다.
• 테스트 모듈을 붙인다.
• 다른 프로젝트로 재사용할 코드가 생긴다.
• 빌드 시간이 커져 include 의존성을 줄이고 싶다.