Unreal Engine 모듈 · 플러그인 개발LESSON 21

Config 파일 저장 범위와 기본값 설계

난이도심화

예상 시간110분

선수지식20강의 UDeveloperSettings

21강. Config 파일 저장 범위와 기본값 설계

1. 이번 강의에서 해결할 문제

개발 PC에서는 설정이 잘 적용되지만 Plugin을 다른 프로젝트로 옮기면 기본값이 사라지거나, Saved/Config를 함께 복사해야만 동작하는 사례가 많습니다. 원인은 코드 기본값, Plugin 기본 Config, 프로젝트 Override, 생성된 로컬 Config의 책임을 섞었기 때문입니다.

2. 학습 목표

3. 핵심 개념

안전한 설정은 세 겹입니다.

코드 기본값: Config가 없어도 기능이 안전하게 동작하는 마지막 방어선
버전 관리 기본값: Plugin 또는 프로젝트가 제공하는 반복 가능한 정책
사용자·실행 환경 값: Saved/Config 아래에 생성될 수 있는 로컬 결과

Saved는 빌드 산출·실행 환경에 따라 재생성되는 영역입니다. 배포 원본으로 간주하거나 Git에 넣지 않습니다. Plugin Config의 병합·패키징 동작은 UE5 마이너 버전과 배포 방식에 따라 차이가 날 수 있으므로 실제 Package 결과를 검사해야 합니다.

4. 단계별 실습

프로젝트 수준의 재현 가능한 기본값을 먼저 둡니다.

Config/DefaultGame.ini
[/Script/ReusableInteraction.InteractionSettings]
DefaultTraceDistance=450.0
DefaultTraceChannel=ECC_Visibility
bDrawDebugTrace=false

Plugin 자체가 독립 기본값을 제공하도록 구성하는 경우 다음 위치도 고려할 수 있습니다.

Plugins/ReusableInteraction/
├─ Config/
│  └─ DefaultReusableInteraction.ini
├─ Source/
└─ ReusableInteraction.uplugin

다만 사용자 정의 Config 이름과 병합 규칙은 엔진 버전·Plugin Descriptor 설정에 따라 달라질 수 있습니다. 가장 이식성이 높은 출발점은 C++ 속성 초기값이며, 프로젝트가 명시적으로 DefaultGame.ini에서 Override하도록 문서화하는 방식입니다.

설정 값을 읽은 뒤 출처를 진단할 수 있는 로그를 추가합니다.

Private/Settings/InteractionSettings.cpp 일부
#include "ReusableInteractionLog.h"

void LogResolvedInteractionSettings()
{
    const UInteractionSettings* Settings = GetDefault<UInteractionSettings>();
    if (!ensure(Settings))
    {
        return;
    }

    UE_LOG(LogReusableInteraction, Display,
        TEXT("Interaction settings: Distance=%.1f Channel=%d Debug=%s"),
        Settings->DefaultTraceDistance,
        static_cast<int32>(Settings->DefaultTraceChannel.GetValue()),
        Settings->bDrawDebugTrace ? TEXT("true") : TEXT("false"));
}

설정 변경 검증표를 만듭니다.

상황	기대 결과	확인 위치
Config 파일 없음	C++ 안전 기본값 사용	Runtime 로그
프로젝트 DefaultGame Override	팀 공통값 사용	소스 관리 파일·로그
Editor UI에서 저장	재시작 뒤 값 유지	Default 또는 Saved Config 변경
Plugin만 빈 프로젝트로 복사	기능이 기본값으로 시작	빈 프로젝트 로그
Shipping 패키지 실행	필요한 설정만 포함	Staged Config·실행 로그

민감한 값이나 사용자 개인정보를 Config에 넣지 않습니다. 이 Plugin은 상호작용 정책만 저장하고 외부 전송 기능을 갖지 않습니다.

5. 코드가 동작하는 이유

Config 시스템은 클래스 경로 섹션과 UPROPERTY를 연결해 계층별 값을 병합합니다. 코드 기본값이 최하단 안전망이고 프로젝트 설정이 의도적으로 이를 덮습니다. 생성 파일에 의존하지 않으면 새 PC와 CI, 빈 프로젝트에서도 같은 출발점을 재현할 수 있습니다.

6. 자주 하는 실수와 해결법

7. 직접 실습

8. 이해 점검 질문 3개

9. 핵심 요약

MINI QUIZ