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

UDeveloperSettings로 플러그인 설정 화면 만들기

난이도심화

예상 시간120분

선수지식19강의 Plugin Module 의존성

20강. UDeveloperSettings로 플러그인 설정 화면 만들기

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

상호작용 거리와 Trace Channel을 Component마다 하드코딩하면 프로젝트를 옮길 때 소스부터 수정해야 합니다. 반대로 모든 값을 Blueprint에 공개하면 기본값의 출처가 분산되고 팀원이 서로 다른 설정으로 테스트할 수 있습니다. Plugin 전체 정책은 한곳에서 보고 버전 관리할 수 있어야 합니다.

2. 학습 목표

3. 핵심 개념

UDeveloperSettings는 Project Settings에 표시할 구성 객체를 만들기 위한 기반 클래스입니다. 이 강의의 설정은 에디터 UI가 아니라 Runtime 정책의 소유자이므로 ReusableInteraction Module에 둡니다. UI에 보이는 것은 Editor가 제공하는 표현이고, 데이터 계약은 Runtime에 남습니다.

엔진 버전에 따라 카테고리·섹션 표시 API와 메타데이터가 달라질 수 있으므로, 사용하는 UE5 버전의 DeveloperSettings.h를 최종 기준으로 확인해야 합니다.

4. 단계별 실습

Public/Settings/InteractionSettings.h
#pragma once

#include "Engine/DeveloperSettings.h"
#include "Engine/EngineTypes.h"
#include "InteractionSettings.generated.h"

UCLASS(Config=Game, DefaultConfig, meta=(DisplayName="Reusable Interaction"))
class REUSABLEINTERACTION_API UInteractionSettings final
    : public UDeveloperSettings
{
    GENERATED_BODY()

public:
    UInteractionSettings();

    UPROPERTY(Config, EditAnywhere, Category="Trace",
        meta=(ClampMin="50.0", UIMin="50.0", Units="cm"))
    float DefaultTraceDistance = 350.0f;

    UPROPERTY(Config, EditAnywhere, Category="Trace")
    TEnumAsByte<ECollisionChannel> DefaultTraceChannel = ECC_Visibility;

    UPROPERTY(Config, EditAnywhere, Category="Debug")
    bool bDrawDebugTrace = false;

    virtual FName GetCategoryName() const override;
};

Private/Settings/InteractionSettings.cpp
#include "Settings/InteractionSettings.h"

UInteractionSettings::UInteractionSettings()
{
    CategoryName = TEXT("Plugins");
    SectionName = TEXT("Reusable Interaction");
}

FName UInteractionSettings::GetCategoryName() const
{
    return TEXT("Plugins");
}

Build.cs에 필요한 Module을 추가합니다.

ReusableInteraction.Build.cs 일부
PublicDependencyModuleNames.AddRange(new[]
{
    "Core", "CoreUObject", "Engine", "DeveloperSettings"
});

Component에서는 기본 객체를 읽되 포인터를 수정하지 않습니다.

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

float UInteractionComponent::ResolveTraceDistance() const
{
    const UInteractionSettings* Settings = GetDefault<UInteractionSettings>();
    if (!ensure(Settings))
    {
        return 350.0f;
    }

    return FMath::Max(50.0f, Settings->DefaultTraceDistance);
}

GetMutableDefault로 플레이 중 설정을 바꾸는 것은 저장 정책과 멀티스레드·테스트 격리를 어렵게 만듭니다. 런타임 중 변해야 하는 값은 Component 인스턴스나 별도 상태 객체로 관리합니다.

5. 코드가 동작하는 이유

Config=Game과 UPROPERTY(Config)가 구성 계층에서 값을 읽도록 하고, DefaultConfig가 프로젝트 기본 설정 파일에 저장 가능한 클래스임을 나타냅니다. CDO인 GetDefault<UInteractionSettings>()를 읽으면 개별 Actor를 만들지 않고도 일관된 Plugin 정책에 접근할 수 있습니다.

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

7. 직접 실습

8. 이해 점검 질문 3개

9. 핵심 요약

MINI QUIZ