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

언리얼 엔진 툴 및 런타임과 함께 별도의 플러그인 개발 방법을 설명합니다.

UE4 에서 플러그인이란 에디터 안에서 프로젝트 단위로 개발자가 쉽게 켜고 끌 수 있는 코드 및 데이터 모음입니다. 플러그인은 런타임 게임플레이 기능을 추가하고, 내장된 엔진 기능을 수정( 또는 새 기능을 추가)하거나, 새 파일 유형을 만들고, 에디터 기존 기능에 새 메뉴, 툴바 명령, 하위 모드를 확장할 수도 있습니다. 여러 기존 UE4 서브시스템은 플러그인을 사용해서 확장 가능하도록 설계되었습니다.

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

에디터의 플러그인 UI

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

플러그인 에디터는 메인 '창' 메뉴에서 접근 가능합니다. 이 인터페이스에는 현재 설치된 플러그인이 전부 표시되어, 플러그인을 개별적으로 켜고 끌 수 있습니다.

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

플러그인은 그 이름과 아이콘, 플러그인 현재 버전, 유용한 설명, 플러그인 저작자 (및 옵션으로 웹 하이퍼링크)와 아울러 플러그인 현재 활성화 여부가 메인 리스트에 표시됩니다.

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

플러그인 디스크립터 아래 Enabled 체크박스를 토글시켜 현재 프로젝트에 사용할 플러그인을 켜고 끌 수 있습니다. 변경사항 적용을 위해서는 에디터를 재시작해야 할 수도 있습니다.

플러그인 해부도

코드가 있는 플러그인에는 Source 폴더가 있습니다. 이 폴더에는 플러그인의 모듈 소스 코드가 들어있는 디렉터리가 하나 이상 있습니다. 참고로 플러그인에는 종종 코드가 들어있지만, 반드시 그럴 필요는 없습니다. 자세한 정보는 플러그인의 코드 부분을 참고하세요.

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

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

Engine 플러그인: [PluginName]/Config/Base[PluginName].ini
Game 플러그인: [PluginName]/Config/Default[PluginName].ini

플러그인은 아직 별도의 파생 데이터 캐시(DDC) 배포를 지원하지 않습니다.

플러그인 폴더

플러그인이 검색되기 위해서는, 프로젝트든 엔진 자체든 검색 경로 중 하나에 위치해야 합니다.

플러그인 유형	검색 경로
Engine	/[UE4 Root]/Engine/Plugins/[Plugin Name]/
Game	/[Project Root]/Plugins/[Plugin Name]/

Plugins 바탕 폴더 아래 서브 디렉터리를 만들어 플러그인에 체계를 세울 수도 있습니다. 엔진은 Plugins 폴더 아래 모든 서브 폴더에서 로드할 플러그인을 검색하지만, 플러그인을 이미 찾은 폴더 아래의 서브 폴더까지 검색하지는 않습니다.

언리얼 엔진은 디스크에서 .uplugin 파일을 검색하는 것으로 플러그인을 찾습니다. 이는 Plugin Descriptors (플러그인 디스크립터)라 하는데, 플러그인에 대한 기본적인 정보를 제공해 줍니다. 플러그인 디스크립터 파일은 언리얼 엔진, 언리얼 에디터, UnrealBuildTool (언리얼 빌드 툴, UBT) 실행시마다 자동으로 발견하여 로드합니다. 이 파일 생성 및 수정 관련해서는 플러그인 디스크립터 파일 부분을 참고하세요.

플러그인의 코드

Visual Studio 나 Xcode 용 프로젝트 파일 생성시, (Build.cs 파일 포함) Source 폴더가 있는 플러그인은 프로젝트 파일에 추가되어 소스 코드 탐색이 쉬워집니다. 이 플러그인은 게임 프로젝트 컴파일시 언리얼 빌드 툴에서 자동 컴파일합니다.

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

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

플러그인은 모듈의 Source (또는 그 하위) 폴더의 헤더 파일에 (UCLASS, USTRUCT 등) 새로운 반영 유형 선언이 가능합니다. 언리얼 엔진 빌드 시스템은 이 파일을 감지하여 새 유형의 지원에 필요한 코드를 생성해 줍니다. C++ 모듈 내 UObject 사용에 관련해서 일반적인 규칙을 따를 필요가 있는데, 이를테면 모듈의 소스 파일 중 하나에 생성 헤더 파일과 모듈의 generated.inl 파일을 포함시키는 것입니다.

UE4 는 상호 종속적인 모듈 및 플러그인을 지원합니다. 프로젝트 모듈은 그 .uproject 파일에서 플러그인을 활성화하여 플러그인에 종속될 수 있습니다. 비슷하게 플러그인은 자체 .uplugin 파일 내 다른 플러그인을 활성화하여 종속성을 나타낼 수 있습니다. 그러나 한 가지 중요한 제약이 있는데, 플러그인과 모듈은 계층적 레벨로 나뉘어 있으며, 같은 레벨 이상의 다른 플러그인 또는 모듈에만 종속될 수 있습니다. 예를 들어 프로젝트 모듈이 엔진 모듈에 종속될 수는 있지만, 엔진 모듈은 프로젝트 모듈에 종속될 수는 없습니다. 왜냐면 엔진(과 그 모든 플러그인 및 모듈)은 어떤 프로젝트보다 상위 레벨이며, 프로젝트 하나 없이도 빌드 가능해야 하기 때문입니다. 다음 도표는 프로젝트와 모듈 사이 종속성 레벨 계층구조를 나타냅니다.

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

엔진 플러그인

언리얼 엔진 4 에는 Engine 디렉터리 아래 내장 플러그인이 몇 개 포함되어 있습니다. 엔진 플러그인은 프로젝트 플러그인과 마찬가지이나, 모든 게임 프로젝트에 사용할 수 있다는 점이 다릅니다. 전형적으로 이 플러그인은 엔진 & 툴 프로그래머가 플러그인 형식으로 만들어서 기본적인 기능을 제공하면 한 곳에 유지한 태 여러 프로젝트에 재사용할 수 있습니다. 이를 통해 사용자가 엔진 코드 수정 없이 전체 엔진 기능을 추가 또는 덮어쓰는 것이 가능합니다.

플러그인의 콘텐츠

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

프로젝트의 플러그인

플러그인은 게임 프로젝트 디렉터리 아래 Plugins 서브폴더에 상주하며, 엔진이나 에디터 시작시 검색 & 로드합니다.

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

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

현재 플러그인 구성 파일은 프로젝트와 같이 패키징되지 않습니다. 앞으로 지원될 수는 있지만, 현재 파일을 프로젝트의 Config 폴더에 수동 복사해야 합니다.

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

플러그인을 패키징하려면, *Package...* 링크를 클릭해서 플러그인을 배포용 폴더에 패키지로 만듭니다.

플러그인 디스크립터 파일

플러그인 디스크립터 파일은 .uplugin 으로 끝나는 파일입니다. 파일 이름 첫 부분은 항상 플러그인 이름입니다. 플러그인 디스크립터 파일은 항상 플러그인 디렉터리에 위치하며, 엔진 시작시 감지합니다.

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

디스크립터 파일 포맷

이 예제 플러그인 디스크립터는 Engine 의 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 (새 플러그인) 버튼을 사용합니다.

여기서 만들려는 플러그인 유형, 이름, 몇 가지 기본 파라미터를 입력하면 됩니다.

플러그인 브라우저에 새 플러그인이 나타나며, 현재 프로젝트에 활성화됩니다.