모듈 은 언리얼 엔진(UE) 의 기본 구성 요소입니다. 엔진은 대규모 모듈 컬렉션으로 구현되며, 게임은 자체 모듈을 제공하여 이를 확장합니다. 각 모듈은 함수 기능 세트를 캡슐화하고 다른 모듈에서 사용할 퍼블릭 인터페이스 및 컴파일 환경(매크로, 인클루드 경로 등)을 제공할 수 있습니다.

모듈은 확장자가 .build.cs 인 C# 소스 파일을 통해 선언되며, 프로젝트의 Source 디렉터리에 저장됩니다. 모듈에 속한 C++ 소스 코드는 .build.cs 파일과 함께 저장되거나 서브디렉터리에 저장됩니다. 각 .build.cs 파일은 ModuleRules 베이스 클래스에서 파생된 클래스를 선언하고 생성자에서 어떻게 빌드되어야 하는지를 제어하는 프로퍼티를 설정합니다. 이러한 .build.cs 파일은 언리얼 빌드 툴(UBT) 로 컴파일되고 전체 컴파일 환경을 결정하도록 구성됩니다.

.build.cs 파일의 일반적인 구조는 다음과 같습니다.

using UnrealBuildTool;
using System.Collections.Generic;
public class MyModule : ModuleRules
{
    public MyModule(ReadOnlyTargetRules Target) : base(Target)
    {
        // 여기에 세팅을 지정합니다.
    }
}

읽기 전용 프로퍼티

IsPlugin (Boolean)

플러그인이 이 모듈을 포함하면 True가 됩니다

HasPackageOverride (Boolean)

이 모듈에 지정된 오버라이드 타입이 있을 경우 True를 반환합니다

AutoSdkDirectory (String)

활성 호스트 플랫폼을 위한 AutoSDK 디렉터리입니다

EngineDirectory (String)

현재 엔진 디렉터리입니다

PluginDirectory (String)

이 플러그인을 포함하는 디렉터리의 프로퍼티입니다. 서드 파티 종속성에 경로를 추가할 때 유용합니다.

ModuleDirectory (String)

이 모듈을 포함하는 디렉터리의 프로퍼티입니다. 서드 파티 종속성에 경로를 추가할 때 유용합니다.

IsVcPackageSupported (Boolean)

빌드 환경설정에 VcPkg가 지원되는지 여부를 반환합니다.

읽기/쓰기 프로퍼티

Type (ModuleType)

모듈 타입입니다.

BinariesSubFolder (String)

DLL을 빌드할 때 이 모듈을 배치할 Binaries/PLATFORM 폴더의 서브폴더입니다 TargetPlatform이나 ShaderFormat 모듈 같이 검색을 통해서 찾아지는 모듈에서만 사용해야 합니다. 트래킹에 FindModules를 사용하지 않으면 모듈을 찾을 수 없습니다.

PrivatePCHHeaderFile (String)

이 모듈에 대한 명시적 프라이빗 PCH입니다. 이 모듈이 공유 PCH를 사용하지 않음을 의미합니다.

SharedPCHHeaderFile (String)

이 모듈에서 제공하는 공유 PCH의 헤더 파일 이름입니다. 퍼블릭 C++ 헤더 파일에 대한 유효한 상대 경로여야 합니다. 여러 C++ 모듈에 포함된 헤더 파일에 대해서만 설정해야 합니다.

ShortName (String)

이 모듈의 중간 디렉터리와 파일에 대체 이름을 지정합니다. 경로 길이 제한에 도달했을 때 유용합니다.

bTreatAsEngineModule (Boolean)

이 모듈을 엔진 모듈(예: 엔진 정의 사용, PCH, DebugGame 환경설정에서 최적화가 활성화된 컴파일 등)로 취급해야 하는지 여부입니다. 생성된 규칙 어셈블리에 기반한 디폴트로 초기화됩니다.

bUseRTTI (Boolean)

런타임 타입 정보를 사용합니다.

bUseAVX (Boolean)

지원하는 플랫폼에서 SSE 또는 AVX 인트린직(intrinsic)을 사용하는 경우 컴파일러가 AVX 인스트럭션을 생성하도록 지시합니다. 이 프로퍼티를 활성화하면 PC 플랫폼의 최소 사양이 변경되며 그에 따른 실행 파일은 AVX 지원 없는 머신에서 충돌합니다.

bEnableBufferSecurityChecks (Boolean)

버퍼 보안 확인을 활성화합니다. 이 프로퍼티는 심각한 보안 위험을 방지하기 때문에 일반적으로 활성화해야 합니다.

bEnableExceptions (Boolean)

예외 처리를 활성화합니다.

bEnableObjCExceptions(Boolean)

오브젝티브 C 예외 처리를 활성화합니다.

bEnableUndefinedIdentifierWarnings(Boolean)

#if 표현식에서 정의되지 않은 식별자를 사용하면 경고를 표시합니다.

MinSourceFilesForUnityBuildOverride(Int32)

Unity 빌드가 이 모듈에 대해 활성화되기 위해 필요한 소스 파일의 수. -1 외의 값으로 설정하면 MinGameModuleSourceFilesForUnityBuild에서 제어하는 디폴트 세팅을 오버라이드합니다.

MinFilesUsingPrecompiledHeaderOverride (Int32)

0이 아니면 BuildConfiguration.MinFilesUsingPrecompiledHeader를 오버라이드합니다.

bBuildLocallyWithSNDBS (Boolean)

모듈이 #import를 사용하여 SN-DBS로 컴파일할 때 로컬에서 빌드해야 합니다.

IsRedistributableOverride (Nullable<Boolean>)

이 모듈의 오버라이드 플래그를 재배포합니다.

bLegalToDistributeObjectCode (Boolean)

모듈에 대해 CarefullyRedist, NotForLicensees, NoRedist가 아닌 코드/종속성이 있는 경우에도 이 모듈의 출력을 공개적으로 배포할 수 있는지 여부입니다. 바이너리는 릴리즈하지만 소스는 릴리즈하지 않으려는 경우 이 프로퍼티를 사용해야 합니다.

AllowedRestrictedFolders (List<String>)

제한된 폴더 이름을 전파하지 않고 이 바이너리를 컴파일할 때 참조하도록 허용되는 폴더 목록입니다

AliasRestrictedFolders (Dictionary<String, String>)

별칭이 지정된 제한된 폴더 레퍼런스 집합입니다.

bEnforceIWYU (Boolean)

PCHUsage가 ExplicitOrSharedPCH로 설정되었을 때 'include what you use(IWYU)' 규칙을 적용합니다. 모놀리식 헤더(Engine.h, UnrealEd.h 등)가 사용될 경우 경고하고 소스 파일에 일치하는 헤더가 포함되어 있는지 먼저 확인합니다.

bAddDefaultIncludePaths (Boolean)

모듈에 연결된 모든 디폴트 인클루드 경로를 추가할지 여부입니다(예: Source/Classes 폴더, Source/Classes 아래의 서브 폴더).

bIgnoreUnresolvedSymbols (Boolean)

모듈에서 허상 (미해결 외부) 심볼을 무시할지 여부입니다.

bPrecompile (Boolean)

이 모듈을 사전 컴파일해야 하는지 여부입니다. 타깃에서 bPrecompile 플래그가 디폴트로 지정됩니다. 모듈이 사전 컴파일되지 않게 하려면 이 플래그를 지우세요.

bUsePrecompiled (Boolean)

이 모듈에서 사전 컴파일된 데이터를 사용해야 하는지 여부입니다. 설치된 어셈블리에서 생성된 모듈의 경우 항상 true입니다.

bAllowConfidentialPlatformDefines (Boolean)

이 모듈이 PLATFORM_XXXX 스타일 정의를 사용할 수 있는지 여부입니다. XXXX는 비밀 플랫폼 이름입니다. 이 프로퍼티는 엔진이나 다른 공유 코드에서 #if PLATFORM_XXXX 블록 내부의 비밀 정보를 노출하지 않도록 하는 데 사용됩니다. 그러나 라이선시 게임 코드에서는 이를 허용하는 것이 좋습니다.

PublicIncludePathModuleNames (List<String>)

모듈의 퍼블릭 헤더가 액세스해야 하지만 '임포트' 또는 링크할 필요는 없는 헤더 파일과 모듈 이름의 목록(경로 필요 없음)입니다.

PublicDependencyModuleNames (List<String>)

퍼블릭 종속성 모듈 이름의 목록(경로 필요 없음)입니다(자동으로 프라이빗/퍼블릭 인클루드 수행). 이러한 모듈은 퍼블릭 소스 파일에 필요한 모듈입니다.

PrivateIncludePathModuleNames (List<String>)

모듈의 프라이빗 코드 파일이 액세스해야 하지만 '임포트' 또는 링크할 필요는 없는 헤더 파일과 모듈 이름의 목록(경로 필요 없음)입니다.

PrivateDependencyModuleNames (List<String>)

프라이빗 종속성 모듈 이름의 목록입니다. 프라이빗 코드는 이 모듈에 의존하지만 퍼블릭 인클루드 파일은 의존하지 않습니다.

CircularlyReferencedDependentModules (List<String>)

레거시 목적으로만 있는 프로퍼티며, 새로운 코드에 사용해서는 안 됩니다. 순환 참조로 취급해야 하는 모듈 종속성의 목록입니다. 이 모듈은 퍼블릭 또는 프라이빗 종속 모듈 목록에 이미 추가되어 있어야 합니다.

PublicSystemIncludePaths (List<String>)

시스템/라이브러리 인클루드 경로 목록입니다. 일반적으로 외부(서드 파티) 모듈에 사용됩니다. 헤더 종속성을 확인할 때 확인되지 않는 안정적인 퍼블릭 헤더 파일 디렉터리입니다.

PublicIncludePaths (List<String>)

('Public' 폴더에서 모든 파일을 검색하기 때문에 현재 필요하지 않은 세팅) 다른 모듈에 노출된 인클루드 파일의 모든 경로 목록입니다.

InternalncludePaths (List<String>)

(현재는 '내부' 폴더에서 모든 파일을 검색하기 때문에 필요하지 않은 세팅) 다른 내부 모듈에 노출되는 파일의 전체 경로 목록입니다

PrivateIncludePaths (List<String>)

이 모듈의 내부 인클루드 파일의 모든 경로 목록으로, 다른 모듈에 노출되지 않습니다('Private' 경로로 최소 1회 인클루드, 상대 경로를 피하려는 경우 인클루드 횟수가 늘어남).

PublicSystemLibraryPaths (List<String>)

시스템 라이브러리 경로 목록입니다(.lib 파일의 디렉터리). 외부 (서드 파티) 모듈의 경우 대신 PublicAdditionalLibaries를 사용하세요.

PrivateRuntimeLibraryPaths (List<String>)

런타임 시 라이브러리의 검색 경로 목록입니다(예: .so 파일).

PublicRuntimeLibraryPaths (List<String>)

런타임 시 라이브러리의 검색 경로 목록입니다(예: .so 파일).

PublicAdditionalLibraries (List<String>)

추가 라이브러리 목록입니다(확장자를 포함한 .lib 파일의 이름). 일반적으로 외부(서드 파티) 모듈에 사용됩니다.

PublicPreBuildLibraries (List<String>)

추가 사전 빌드 라이브러리의 목록입니다(확장자를 포함한 .lib 파일의 이름). 일반적으로 아직 빌드 중인 추가 타깃에 사용되지만 TargetRules.PreBuildSteps 또는 TargetRules.PreBuildTargets 중 하나를 사용합니다.

PublicSystemLibraries (List<String>)

사용할 시스템 라이브러리의 목록입니다. 일반적으로 이름을 통해 참조된 후 시스템 경로를 통해 찾을 수 있습니다. .lib 파일을 참조해야 할 경우 대신 PublicAdditionalLibraries를 사용하세요.

PublicFrameworks (List<String>)

XCode 프레임워크의 목록입니다(iOS 및 MacOS).

PublicWeakFrameworks(List<String>)

약한 프레임워크의 목록입니다(OS 버전 트랜지션용).

PublicAdditionalFrameworks (List<Framework>)

추가 프레임워크의 목록입니다. 일반적으로 Mac 및 iOS의 외부(서드 파티) 모듈에 사용됩니다.

AdditionalBundleResources (List<BundleResource>)

Mac 또는 iOS의 앱 번들에 복사해야 하는 추가 리소스 목록입니다.

TypeLibraries (List<TypeLibrary>)

헤더를 생성해야 하는 타입 라이브러리의 목록입니다(Windows 전용).

PublicDelayLoadDLLs (List<String>)

딜레이 로드 DLL 목록입니다. 일반적으로 외부(서드 파티) 모듈에 사용됩니다.

PrivateDefinitions (List<String>)

이 모듈에 대한 프라이빗 컴파일러 정의입니다.

PublicDefinitions(List<String>)

이 모듈에 대한 퍼블릭 컴파일러 정의입니다.

DynamicallyLoadedModuleNames (List<String>)

런타임 시 이 모듈에 필요할 수 있는 추가 모듈입니다.

RuntimeDependencies (RuntimeDependencyList)

런타임 시 이 모듈이 의존하는 파일의 목록입니다. 이 파일은 타깃과 함께 스테이징됩니다.

AdditionalPropertiesForReceipt (ReceiptPropertyList)

빌드를 받을 때 추가할 추가 프로퍼티 목록입니다.

PrecompileForTargets (PrecompileTargetsType)

이 모듈을 사전 컴파일해야 하는 타깃입니다.

ExternalDependencies (List<String>)

수정 시 makefile을 무효화하는 외부 파일입니다. 상대 경로는 .build.cs 파일을 기준으로 해석됩니다.

AdditionalCodeGenDirectories (List<String>)

생성된 interop 파일이 포함된 외부 디렉터리입니다.

SubclassRules (List<String>)

수정 시 makefile을 무효화하는 서브클래스 규칙 파일입니다.

bRequiresImplementModule (Nullable<Boolean>)

이 모듈이 IMPLEMENT_MODULE 매크로를 구현해야 하는지 여부입니다. 글로벌 오버로드를 수행하기 위해 IMPLEMENT_MODULE 매크로를 사용하기 때문에 대부분의 UE 모듈에는 이 프로퍼티가 필요합니다(예: GMalloc에 포워딩하는 신규/삭제 연산자).

CppStandard (CppStandardVersion)

이 모듈을 컴파일하는 데 사용할 표준입니다.

ModuleSymbolVisibility (SymbolVisibility)

심볼 가시성을 제어합니다.

Name (String)

이 모듈의 이름입니다

OverridePackageType (PackageOverrideType)

서로 다른 패키지 플래그가 설정되는 모듈의 오버라이드 타입입니다. 모듈이 플러그인의 일부인 경우 이미 .uplugin 파일에 설정되어 있기 때문에 사용할 수 없습니다.

OptimizeCode (CodeOptimization)

이 모듈의 코드가 최적화되어야 하는 상황입니다.

PCHUsage (PCHUsageMode)

이 모듈의 사전 컴파일된 헤더 사용입니다

DefaultBuildSettings (BuildSettingsVersion)

기본적으로 어느 엔진 버전의 빌드 세팅을 사용하는지입니다.

ShadowVariableWarningLevel (WarningLevel)

섀도 변수 경고를 처리하는 방법입니다

UnsafeTypeCastWarningLevel (WarningLevel)

안전하지 않은 묵시적 타입 형변환 경고를 어떻게 처리할지입니다(예: double->float 또는 int64->int32)

bUseUnity (Boolean)

Unity 빌드가 활성화되었고 이 특정 모듈이 Unity를 사용하여 빌드할 경우 이것을 사용하여 오버라이드할 수 있습니다. BuildConfiguration의 모듈별 환경설정을 사용하여 설정할 수 있습니다.

bLegacyPublicIncludePaths (Boolean)

이 모듈이 'Public' 폴더의 루트를 기준으로 다른 모듈에서 포함된 헤더에 적합한지 여부입니다. 이렇게 하면 컴파일러에 전달해야 하는 검색 경로의 수가 줄어들어, 퍼포먼스가 향상되고 컴파일러 명령줄 길이가 줄어듭니다.