언어:
페이지 정보
엔진 버전:
언리얼 엔진

플러그인

언리얼 엔진

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

다수의 언리얼 엔진 시스템은 확장성을 염두에 두고 디자인되어, 엔진 코드를 직접 수정하지 않아도 완전히 새로운 기능을 추가하고 내장 기능을 변경하는 것이 가능합니다. 에디터에 새로운 파일 유형을 만들어 새 메뉴 항목과 툴바 명령은 물론, 심지어 완전 새로운 기능과 에디터 서브 모드를 추가하는 것도 가능합니다!

지금 바로 플러그인에 뛰어들어 보시려거든, 플러그인 예제 섹션을 참고해 주세요.

플러그인 에디터 UI

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

PluginsEditor.png

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

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

PluginCategories.png

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

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

SearchingPlugins.png

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

플러그인 해부도

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

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

플러그인에는 해당 플러그인 전용 애셋 파일이 들어있는 Content 폴더가 있을 수 있습니다. 자세한 정보는 플러그인의 콘텐츠 부분을 참고하세요.

플러그인은 아직 환경설정 파일을 지원하지 않습니다만, 추후 지원을 고려하고 있습니다.

또 플러그인은 아직 별도의 파생 데이터 캐시(DDC) 배포를 지원하지 않습니다. 추후 지원할 것인지 검토중입니다.

플러그인 폴더

플러그인은 항상 플러그인 디렉터리에 위치합니다. 플러그인이 검색되기 위해서는, 언리얼 엔진의 플러그인에 유효한 검색 경로 중 하나에 위치해야 합니다.

플러그인 유형

검색 경로

Engine

/UE4 Root/Engine/Plugins/My Engine Plugin/

Game

/My Project/Plugins/My Game Plugin/

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

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

플러그인의 코드

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

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

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

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

플러그인 모듈이 약간 다른 한 가지는, "Public" 소스 파일 헤더입니다. 대부분의 플러그인 모듈에는 Public 폴더의 헤더 파일에서 공용 API 를 익스포트할 일이 없는데, 엔진 또는 게임 코드에 직접 종속될 (정적으로 링크될) 일이 절대 없기 때문입니다. 그래서 보통 Public 소스 폴더는 비어있게 됩니다. 이 규칙에 몇 가지 예외가 있습니다:

  • 플러그인에 다수의 C++ 모듈이 들어있는 경우, Public 폴더의 코드가 플러그인 내 여러 모듈에 공유될 수 있습니다.

  • (엔진이 아닌) 게임 플러그인 제작시 게임에서 다른 플러그인 모듈 중 하나에 정적 링크를 허용하고자 할 때입니다. 플러그인 개념이 약간 깨집니다만, 플러그인에서 새 UObject 유형을 선언하여 게임 클래스가 상속하거나 직접 사용할 수 있도록 하면 유용한 경우가 종종 있습니다. 엔진 자체는 이 플러그인에 종속성이 없지만, 게임 프로젝트 코드와 콘텐츠는 직접 종속성이 있을 수도 있습니다.

  • 플러그인과 함께 공용 인터페이스 헤더를 배포하고자 하는 경우, 게임 코드나 다른 플러그인에서 해당 플러그인 모듈에 구현된 유형에 접근하도록 하고자 할 때입니다. 흔치 않으며 일반적으로 권장하지 않는 방법인데, 현재 다른 플러그인에 직접 종속되는 플러그인 지원 계획은 없기 때문입니다.

플러그인의 콘텐츠

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

게임 프로젝트의 플러그인

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

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

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

엔진 플러그인

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

기본적으로 엔진 플러그인은 다른 게임 모듈이나 게임 프로젝트 플러그인 로드 전 로드됩니다.

엔진 플러그인에는 특별한 요건이 있습니다: 엔진 코드 모듈은 엔진 플러그인 모듈 라이브러리에 대한 정적 링크가 있어서는 안됩니다. 즉, 엔진 플러그인은 반드시 엔진 자체와는 분리된 형태로 있어야 하며, 플러그인이 엔진 모듈의 "종속성 모듈" 이 되어서는 안된다는 뜻입니다. 이는 철학적 선택에 의한 것으로, 플러그인을 로드할 수 없어도 엔진의 정상 작동에는 영향을 끼쳐서는 안되기 때문입니다.

플러그인 배포

플러그인 배포를 위한 절차입니다.

  1. Make sure the modules list in your .uplugin file has a correct list of whitelisted and blacklisted platforms.

  2. Find your plugin in the editor's plugin browser, and click the 'Edit...' link to update the metadata associated with your plugin (description, link to documentation, and so on).

  3. Click the '**Package...*' link to package your plugin into a folder for distribution.

By default, only source code, binaries and content will be packaged with your plugin. If you have additional files you need to include, create a file called Config/FilterPlugin.ini in your plugin folder which lists additional paths to include, like this:

[FilterPlugin]
/ThirdParty/...
/MyOtherFolder/...

중요 참고사항:

  • 콘텐츠 포함 플러그인의 경우, 플러그인에 생성 파생 데이터(DDC)를 포함시켜 최종 사용자가 필요시 생성할 필요가 없도록 하고싶을 수가 있습니다. 이 기능은 아직 지원되지 않지만, 나중에 추가될 것입니다. 기대해 주세요.

  • 배포 플러그인에 EULA 또는 다른 문서를 포함시키는 것이 아직 지원되지 않습니다. 나중에 지원할 수 있습니다.

플러그인 설명 파일

플러그인 설명 파일은 .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"
        }
    ]
}

설명 파일 포맷

필드명

정보

설명

FileVersion

필수

이 플러그인 설명 파일 자체 버전입니다. 플러그인 시스템에 신기능 추가시의 하위 호환성 유지에 사용됩니다. 보통 사용중인 엔진 버전에 허용되는 최신 버전으로 설정해야 합니다. 최신 버전은 현재 3 으로, 이 문서에 기록된 포맷 버전입니다. 이 버전이 매우 자주 바뀔 것으로는 생각지 않습니다. 소스 코드에서 EProjectDescriptorVersion 를 보시면 실제 값을 확인할 수 있습니다. 엔진 구버전과 최대한 호환되도록 하기 위해서는, 포맷 구버전을 사용하면 되지만 추천하지는 않습니다.

Version

옵션

플러그인 이 빌드의 버전입니다. 이 값은 계속해서 증가할 것입니다. 이 버전은 보통 최종 사용자에게 표시되지 않습니다.

VersionName

옵션

에디터 UI 에 표시되는 플러그인 버전입니다. 어떤 버전 검사에도 사용되지 않으며, 포맷은 어떻게 해도 상관없지만, 주요.사소 포맷으로 하는 것이 좋습니다. Version 이 오르면 VersionName 도 업데이트하는 것이 좋습니다.

FriendlyName

옵션

에디터 UI 에 표시되는 플러그인 이름입니다. 지정되지 않으면, .uplugin 파일명이 기본으로 사용됩니다.

Description

옵션

이 플러그인의 용도를 설명하는 문구입니다. 에디터 플러그인 창에 표시됩니다.

Category

옵션

플러그인을 에디터 UI 의 카테고리에 할당할 수 있도록 해 주는 점 구분 경로 문자열입니다. 순전히 체계를 위한 용도입니다. 카테고리 경로 예제는 "Editor Features.Level Editing.Mesh Painting" 식입니다. 각 카테고리는 점으로 구분되며, 트리 구조의 단계를 나타냅니다.

CreatedBy

옵션

이 플러그인을 만든 개인 또는 회사 이름입니다. 플러그인 UI 또는 다른 위치에 표시될 수 있습니다.

CreatedByURL

옵션

이 플러그인을 만든 개인 또는 회사 웹 링크입니다. 지정된 경우 사용자가 웹 페이지를 방문할 수 있도록 에디터 UI 에 링크가 표시됩니다.

DocsURL

옵션

플러그인 문서에 대한 웹 링크입니다. 지정된 경우 에디터의 플러그인 브라우저에 하이퍼링크가 표시되어 사용자가 이 웹 페이지를 볼 수 있게 될 것입니다.

MarketplaceURL

옵션

플러그인의 마켓플레이스 페이지 링크입니다. 지정된 경우, 에디터의 플러그인 브라우저에 하이퍼링크가 표시되어 사용자가 이 웹 페이지를 둘러볼 수 있습니다.

SupportURL

옵션

플러그인 기술지원 페이지 링크입니다. 지정된 경우 에디터의 플러그인 브라우저에 표시됩니다.

EnabledByDefault

옵션

true 면 이 플러그인이 존재하는 경우 자동으로 켜집니다.

CanContainContent

옵션

true 로 설정된 경우, 이 플러그인의 콘텐츠 지원을 활성화시킵니다. 기본값은 false 입니다. 자세한 정보는 플러그인의 콘텐츠 부분을 참고하세요.

IsBetaVersion

옵션

콘텐츠를 베타 버전으로 마킹합니다. 이 항목에 대해 플러그인 목록에서 "Version" 이 "BETA Version" 으로 대체됩니다.

Installed

옵션

true 로 설정되면, 이 플러그인은 플러그인 목록의 "Project" 또는 "Built-in" 섹션이 아닌 "Installed" 섹션에 나타납니다.

Modules

옵션

소스 코드(와 바이너리)가 포함된 플러그인의 경우, 시작시 로드할 모듈 목록입니다. 자세한 정보는 아래를 참고하세요.

모듈 설명

코드가 포함된 플러그인의 경우, 설명 파일에는 최소 하나의 모듈 설명이 포함됩니다.

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

필드명

정보

설명

Name

필수

플러그인과 함께 로드될 이 플러그인 모듈의 고유명입니다. 실행시간에, 엔진은 여기 지정된 것과 같은 모듈명으로 플러그인의 Binaries 폴더에 적합한 플러그인 바이너리가 있을 것으로 기대합니다. Source 디렉터리가 있는 모듈의 경우, 모듈의 서브 폴더 트리 안에 일치하는 *.Build.cs 파일이 존재할 것으로 기대합니다.

Type

필수

모듈 유형을 설정합니다. 유효한 옵션은 Runtime, RuntimeNoCommandlet, Developer, Editor, EditorNoCommandlet, Program 입니다. 이 유형은 이 플러그인의 모듈을 로드하기에 적합한 어플리케이션 유형을 결정합니다. 예를 들어 어떤 플러그인은 에디터 실행중에만 로드되도록 디자인된 모듈이 포함되어 있을 수가 있습니다. Runtime 모듈은 발매 게임에서도 모든 경우에 로드됩니다. Developer 모듈은 개발 런타임 또는 에디터 빌드에만 로드되나, 쉬핑 빌드에는 로드되지 않습니다. Editor 모듈은 에디터 시작시에만 로드됩니다. 플러그인은 다양한 유형의 모듈 조합을 사용할 수 있습니다.

LoadingPhase

옵션

지정되면, 시작시 플러그인 로드 시점을 제어합니다. 일반적으로는 필요치 않은 고급 옵션입니다. 유효한 옵션은 Default (LandingPhase 가 지정되지 않았을 때 사용), PreDefault, PostConfigInit 입니다. PostConfigInit 는 엔진이 핵심 서브 시스템 시동을 마치기 전 모듈 로드가 가능합니다. PreDefault 는 보통 페이즈 바로 직전에 로드합니다. 전형적으로 게임 모듈이 플러그인 내 콘텐츠나 플러그인 코드 내 선언된 유형에 직접 의존할 필요가 있을 때만 필요합니다.

WhitelistPlatforms

옵션

지정되면, 이 모듈 컴파일 대상이 되는 플랫폼 목록을 제공합니다. 지정되지 않으면, 모든 플랫폼에 대해 컴파일합니다.

BlacklistPlatforms

옵션

지정되면, 이 모듈 컴파일 대상에서 제외되는 플랫폼 목록을 제공합니다. 지정되지 않으면, 모든 플랫폼에 대해 컴파일합니다.

아이콘 파일

설명 파일과 함께 플러그인은 보통 에디터 UI 에서 플러그인을 표시할 때 사용되는 아이콘 파일이 있습니다.

파일명

정보

포맷

설명

/Resources/Icon128.png

필수

128x128 PNG 파일

에디터 UI 에 이 플러그인을 나타내는 아이콘입니다. 메인 창 메뉴에서 접근할 수 있는 '플러그인' 유저 인터페이스에 나타납니다.

플러그인 예제

별다른 기능은 없으나 직접 플러그인을 만들 때 템플릿으로 사용할 수 있는 예제 플러그인을 만들어 봤습니다. 엔진 소스 코드가 포함되어 있습니다.

예제 이름

정보

BlankPlugin

이 플러그인은 새 코드 플러그인 모듈 구성에 필요한 최소한의 파일을 보여주는 빈 껍데기입니다.

UObjectPlugin

별도의 UObject 클래스를 선언하는 법을 보여주는 간단한 기본 플러그인입니다.

이 예제를 사용해서 플러그인 제작을 시작하려면:

  1. 예제 플러그인을 새 폴더로 복사한 다음 디렉터리, 파일, 코드 콘텐츠를 새 플러그인 이름에 맞게 변경합니다. 기존 이름 그대로 놔두는 것은 좋지 않은데, 엔진에 내장된 플러그인과 충돌할 수 있기 때문입니다.

  2. 게임 프로젝트 디렉터리 아래 "Plugins" 폴더를 만들고, 플러그인을 "Plugins" 아래 서브폴더에 복사합니다.

    ExamplePlugins.png

  3. C++ 프로젝트 파일을 리빌드합니다. 플러그인 모듈과 소스 코드가 프로젝트 파일 내 프로젝트 디렉터리 아래 디렉터리에 나타납니다.

  4. 정상적으로 게임 프로젝트를 컴파일합니다. 언리얼 빌드 툴이 플러그인을 게임의 종속성으로 감지하여 컴파일합니다!

  5. 에디터를 실행합니다 (또는 게임). 플러그인이 처음에는 꺼져있지만, 에디터 UI 에서 켤 수 있습니다.

  6. 플러그인 에디터를 엽니다 (창 -> 플러그인). 플러그인을 검색한 뒤 체크박스를 클릭하여 켭니다.

  7. 에디터를 재시작합니다. 플러그인이 시작시 자동으로 로드 됩니다.

창 -> 개발자 툴 메뉴 아래에서 모듈 뷰어를 열면 플러그인이 로드된 것을 확인할 수 있습니다. 또다른 방법은 코드 디버거를 사용해서 FBlankPlugin::StartupModule() 같은 플러그인 시작 코드에 중단점을 배치하는 것입니다.