언리얼 엔진의 플러그인 | 언리얼 엔진 5.4 문서

이 페이지에서는 언리얼 엔진 툴과 런타임에서 사용하기 위한 플러그인 을 개발하고 관리하는 방법을 살펴봅니다.

언리얼 엔진에서 플러그인은 개발자가 프로젝트 단위로 에디터 내에서 손쉽게 활성화하거나 비활성화할 수 있는 코드 및 데이터 컬렉션입니다. 플러그인은 런타임 게임플레이 기능을 추가하고, 내장 엔진 기능을 수정하거나 새로운 엔진 기능을 추가하며, 새로운 파일 타입을 생성하고, 새로운 메뉴, 툴바 명령, 서브 모드를 통해 에디터 기능을 확장할 수 있습니다. 기존의 여러 언리얼 엔진 서브시스템은 플러그인을 사용하여 확장할 수 있도록 디자인되었습니다.

플러그인을 바로 생성하려면 새 플러그인 생성하기 섹션을 참고하세요.

에디터의 플러그인 UI

편집(Edit) 메뉴에서 플러그인 편집 인터페이스를 열면 현재 설치된 플러그인을 확인할 수 있습니다.

플러그인 에디터는 메인 '창(Window)' 메뉴에서 액세스할 수 있습니다. 이 인터페이스에는 현재 설치된 플러그인이 모두 표시되며, 플러그인을 개별적으로 활성화하거나 비활성화할 수 있습니다.

왼쪽의 트리 인터페이스를 통해 플러그인을 카테고리별로 탐색할 수 있습니다. 카테고리를 선택하면 해당 카테고리의 모든 플러그인과 아울러 서브 카테고리가 있는 경우 여기에 포함된 플러그인도 표시됩니다. 카테고리를 탐색할 때 UI 상단에 탐색 경로 트레일이 표시되어 상위 레벨 카테고리로 빠르게 점프할 수 있습니다. 카테고리 옆의 숫자는 해당 카테고리에 있는 플러그인의 수를 나타냅니다.

플러그인은 해당 이름과 아이콘, 플러그인 현재 버전, 유용한 설명, 플러그인 저작자 및 선택적 웹 하이퍼링크와 플러그인의 현재 활성화 여부가 메인 목록에 표시됩니다.

상단의 검색창을 통해 목록에 표시되는 플러그인을 이름을 기준으로 검색할 수 있습니다.

플러그인의 설명 아래에서 활성화됨(Enabled) 체크박스를 토글하면 현재 프로젝트에 사용할 플러그인을 활성화하거나 비활성화할 수 있습니다. 변경사항을 적용하기 위해서는 에디터를 재시작해야 할 수도 있습니다.

플러그인 분석

코드를 갖춘 플러그인에는 Source 폴더가 있습니다. 이 폴더에는 플러그인의 모듈 소스 코드가 들어있는 디렉터리가 하나 이상 있습니다. 참고로, 플러그인은 코드를 포함하는 경우가 많지만 반드시 그럴 필요는 없습니다. 자세한 내용은 플러그인의 코드 섹션을 참고하세요.

코드 모듈이 있는 플러그인의 경우, 플러그인은 해당 플러그인의 컴파일된 코드가 들어있는 Binaries 폴더가 있습니다. 또한 임시 빌드 결과물 파일은 플러그인 디렉터리 아래에 있는 별도의 Intermediate 폴더에 저장됩니다.

플러그인에는 해당 플러그인 전용 에셋 파일이 들어있는 Content 폴더가 있을 수 있습니다. 자세한 내용은 플러그인의 콘텐츠 섹션을 참고하세요. 플러그인 환경설정 파일은 다른 파일과 동일한 규칙을 사용해야 합니다.

엔진 플러그인: [PluginName]/Config/Base[PluginName].ini
게임 플러그인: [PluginName]/Config/Default[PluginName].ini

플러그인은 자체 파생 데이터 캐시(Derived Data Cache, DDC) 배포를 지원하지 않습니다.

플러그인 폴더

플러그인을 검색할 수 있기 위해서는 프로젝트든 엔진 자체든 검색 경로 중 하나에 있어야 합니다.

플러그인 타입	검색 경로
엔진	`[Unreal Engine Root Directory]/Engine/Plugins/[Plugin Name]/`
게임	`[Project Root Directory]/Plugins/[Plugin Name]/`

또한 베이스 Plugins 폴더 아래에 서브 디렉터리를 생성하여 플러그인을 정리할 수도 있습니다. 엔진이 베이스 Plugins 폴더 아래에 있는 모든 서브 폴더에서 로드할 플러그인을 검색하지만, 플러그인을 이미 찾은 폴더 아래의 서브 폴더는 검색하지 않습니다.

언리얼 엔진은 디스크에서 .uplugin 파일을 검색하여 플러그인을 찾습니다. 이러한 파일을 플러그인 디스크립터 라고 합니다. 이러한 텍스트 파일은 플러그인에 대한 기본적인 정보를 제공합니다. 플러그인 디스크립터는 해당 프로그램이 실행될 때마다 엔진, 에디터 및 언리얼 빌드 툴(UnrealBuildTool, UBT)에서 자동으로 검색 및 로드됩니다. 이러한 파일을 생성하고 커스터마이징하는 방법에 대한 자세한 내용은 플러그인 디스크립터 파일 섹션을 참고하세요.

플러그인의 코드

Visual Studio 또는 Xcode용 프로젝트 파일을 생성하는 경우 .Build.cs 파일을 포함하는 Source 폴더가 있는 플러그인은 프로젝트 파일에 추가되어 소스 코드를 손쉽게 탐색할 수 있습니다. 이러한 플러그인은 게임 프로젝트를 컴파일할 때 언리얼 빌드 툴에서 자동으로 컴파일합니다.

플러그인은 모듈 소스 디렉터리를 몇 개든 가질 수 있습니다. 대부분의 플러그인은 하나의 모듈만 가질 수 있지만 여러 개의 모듈을 생성하는 것도 가능합니다. 예를 들어 에디터 전용으로만 컴파일되는 기능이 있고, 런타임 게임에 필요한 코드가 따로 있을 수 있습니다.

대부분의 경우, 플러그인 소스 파일의 레이아웃은 언리얼 엔진의 다른 C++ 모듈과 동일합니다.

플러그인은 모듈의 Source 디렉터리 또는 그 하위 디렉터리의 헤더 파일에 UCLASS, USTRUCT 같은 새로운 반영 타입을 선언할 수 있습니다. 언리얼 엔진의 빌드 시스템은 이러한 파일을 탐지하여 새 타입을 지원하는 데 필요한 코드를 생성합니다. C++ 모듈 내에서 UObjects 를 사용하는 것과 관련해서는 일반적인 규칙을 따를 필요가 있습니다. 여기에는 모듈의 소스 파일 중 하나에 생성 헤더 파일과 모듈의 generated.inl 파일을 포함시키는 것이 포함됩니다.

언리얼 엔진은 상호 종속적인 모듈 및 플러그인을 지원합니다. 프로젝트 모듈은 해당 .uproject 파일에서 플러그인을 활성화하여 플러그인에 종속될 수 있습니다. 이와 유사하게 플러그인은 자체 .uplugin 파일 내에서 다른 플러그인을 활성화하여 종속성을 나타낼 수 있습니다. 하지만 플러그인과 모듈은 계층적 레벨로 나뉘어 있으며 동일한 레벨 이상의 다른 플러그인 또는 모듈에만 종속될 수 있다는 중요한 제한이 적용됩니다. 예를 들어 프로젝트 모듈이 엔진 모듈에 종속될 수는 있지만, 엔진 모듈은 프로젝트 모듈에 종속될 수 없습니다. 이는 엔진과 모든 해당 플러그인 및 모듈은 어떤 프로젝트보다 상위 레벨이며, 프로젝트 없이도 빌드할 수 있어야 하기 때문입니다. 아래의 다이어그램은 프로젝트와 모듈 사이의 종속성 레벨 계층구조를 나타냅니다.

화살표는 가능한 종속성을 나타냅니다. 각 플러그인 또는 모듈 타입은 자체 레벨 이상의 다른 항목에 종속될 수 있습니다.

엔진 플러그인

언리얼 엔진은 Engine 디렉터리 아래에 내장 플러그인을 몇 개 포함하고 있습니다. 엔진 플러그인은 프로젝트 플러그인과 비슷하지만 모든 게임 프로젝트에 사용할 수 있다는 점이 다릅니다. 일반적으로 엔진 및 툴 프로그래머가 이러한 플러그인을 제작하여 기본적인 기능을 제공하면 단일 위치에서 유지관리하며 여러 프로젝트에서 재사용할 수 있습니다. 이를 통해 사용자는 엔진 코드를 수정하지 않고도 전체 엔진 기능을 추가하거나 오버라이드할 수 있게 됩니다.

플러그인의 콘텐츠

언리얼 엔진은 게임 콘텐츠는 물론 바이너리 코드가 포함된 플러그인도 지원합니다. 플러그인의 콘텐츠를 사용하기 위해서는 플러그인 디스크립터의 'CanContainContent' 세팅을 'true'로 설정해야 합니다.

프로젝트의 플러그인

플러그인은 게임 프로젝트 디렉터리 아래에 있는 Plugins 하위 폴더에 있으며, 엔진 또는 에디터 스타트업 시 탐지 및 로드됩니다.

플러그인에 Source 폴더 및 .Build.cs 파일이 있는 모듈이 포함되어 있는 경우, 플러그인 코드가 생성된 C++ 프로젝트 파일에 자동으로 추가되어 프로젝트와 함께 플러그인도 손쉽게 개발할 수 있습니다. 프로젝트를 컴파일할 때마다 Source 가 있는 플러그인도 게임의 종속성으로 함께 컴파일됩니다.

Source 폴더가 없는 플러그인은 프로젝트 제너레이터에 의해 무시되며, C++ 프로젝트 파일에 나타나지 않습니다. 하지만 바이너리 파일이 존재하는 한 스타트업 시 로드됩니다.

현재 플러그인 환경설정 파일은 프로젝트와 함께 패키징되지 않습니다. 앞으로 지원될 수는 있지만 현재는 해당 파일을 프로젝트의 Config 폴더에 수동으로 복사해야 합니다.

에픽 마켓플레이스에 플러그인 배포하기

플러그인을 패키징하려면 패키지...(Package...) 링크를 클릭하여 플러그인을 배포용 폴더에 패키징합니다.

플러그인 사전 컴파일하기

언리얼 엔진 5.2용 플러그인을 사전 컴파일하는 경우, 언리얼 엔진 5.2에 대한 Visual Studio 최소 지원 버전인 Visual Studio 2019를 사용하여 플러그인을 컴파일합니다. Visual Studio 2019를 사용하여 컴파일하면 모든 사용자에 대해 결과 라이브러리가 언리얼 엔진 5.2와 호환됩니다. Visual Studio 및 언리얼 엔진의 버전 호환성에 대한 자세한 내용은 Visual Studio 구성하기를 참고하세요.

플러그인 디스크립터 파일

플러그인 디스크립터 파일은 .uplugin 으로 끝나는 파일입니다. 파일 이름 첫 부분에는 항상 플러그인 이름이 옵니다. 플러그인 디스크립터 파일은 항상 플러그인 디렉터리에 있으며, 스타트업 시 엔진에서 이를 검색합니다.

플러그인 디스크립터는 JSON(JavaScript Object Notation) 파일 포맷으로 되어 있습니다.

디스크립터 파일 포맷

이 예시 플러그인 디스크립터는 엔진의 UObjectPlugin 에서 가져온 것입니다.

{
    "FileVersion" : 3,
    "Version" : 1,
    "VersionName" : "1.0",
    "FriendlyName" : "UObject Example Plugin",
    "Description" : "An example of a plugin which declares its own UObject type.  This can be used as a starting point when creating your own plugin.",
    "Category" : "Examples",
    "CreatedBy" : "Epic Games, Inc.",
    "CreatedByURL" : "http://epicgames.com",
    "DocsURL" : "",
    "MarketplaceURL" : "",
    "SupportURL" : "",
    "EnabledByDefault" : true,
    "CanContainContent" : false,
    "IsBetaVersion" : false,
    "Installed" : false,
    "Modules" :
    [
        {
            "Name" : "UObjectPlugin",
            "Type" : "Developer",
            "LoadingPhase" : "Default"
        }
    ]
}

디스크립터 파일 포맷

디스크립터 파일은 FPluginDescriptor 타입을 따르는 JSON 포맷 변수 목록입니다. 'FileVersion'이라는 추가 필드가 하나 있는데, 이 구조체에서 유일한 필수 필드입니다. 'FileVersion'은 플러그인 디스크립터 파일의 버전을 나타내며, 일반적으로 엔진에서 허용되는 가장 높은 버전을 지정해야 합니다(현재는 '3'). 이 버전은 플러그인 자체가 아닌 플러그인 디스크립터 파일 포맷에 적용되기 때문에 자주 변경되지는 않으며 플러그인 향후 버전 출시에 맞춰 변경하면 됩니다. 이전 엔진 버전과의 호환성을 극대화하기 위해서는 이전 버전 번호를 사용하면 되지만 권장하지는 않습니다.

지원되는 다른 필드와 관련된 자세한 내용은 API 레퍼런스 페이지를 참고하세요.

부울 변수에 대한 필드 이름에는 변수 이름 처음에 오는 'b'가 빠져 있습니다. 예를 들어 bEnabledByDefault 변수는 'EnabledByDefault' 필드에 해당합니다.

모듈 디스크립터

코드가 포함되어 있는 플러그인의 경우, 디스크립터 파일의 'Modules' 필드는 최소 한 항목을 포함합니다. 예시 항목은 다음과 같습니다.

{
    "Name" : "UObjectPlugin",
    "Type" : "Developer"
    "LoadingPhase" : "Default"
}

각 항목에는 'Name' 및 'Type' 필드가 있습니다. 'Name'은 플러그인과 함께 로드될 이 플러그인 모듈의 고유한 이름입니다. 런타임에서 엔진은 해당 플러그인의 'Binaries' 폴더에 적합한 플러그인 바이너리가 여기에 지정된 모듈 이름으로 있을 것으로 예상합니다. Source 디렉터리가 있는 모듈의 경우, 모듈의 서브 폴더 트리 내에 일치하는 '.Build.cs' 파일이 존재할 것으로 예상합니다. 'Type'은 모듈의 타입을 설정합니다. 유효한 옵션은 Runtime, RuntimeNoCommandlet, Developer, Editor, EditorNoCommandlet 및 Program 입니다. 이 타입은 이 플러그인의 모듈을 로드하는 데 적합한 어플리케이션의 타입을 결정합니다. 예를 들어 어떤 플러그인은 에디터가 실행 중인 경우에만 로드되도록 디자인된 모듈이 포함되어 있을 수 있습니다. Runtime 모듈은 출시 게임에서도 모든 경우에 로드됩니다. Developer 모듈은 개발 런타임 또는 에디터 빌드에서만 로드되지만 출시 빌드에는 로드되지 않습니다. Editor 모듈은 에디터 스타트업 시에만 로드됩니다. 플러그인은 다양한 타입의 모듈 조합을 사용할 수 있습니다.

제공되는 다른 필드와 관련된 자세한 내용은 레퍼런스 페이지를 참고하세요.

아이콘

디스크립터 파일과 함께 플러그인은 에디터 플러그인 브라우저에 표시할 아이콘이 필요합니다. 이미지는 128x128 .png 파일로, 이름은 'Icon128.png'여야 하며 플러그인의 '/Resources/' 디렉터리에 유지됩니다.

새 플러그인 생성하기

새 플러그인을 생성하려면 에디터 플러그인 브라우저의 새 플러그인(New Plugin) 버튼을 사용합니다.

여기서 제작하려는 플러그인 타입, 이름 및 몇 가지 기본 파라미터를 입력하면 됩니다.

플러그인 브라우저에 새 플러그인이 표시되고 현재 프로젝트에서 활성화됩니다.