Unreal Engine でのプラグイン | Unreal Engine 5.5 ドキュメンテーション

このページでは、Unreal Engine (UE) のツールやランタイムで使用する プラグイン の開発と管理について説明します。

Unreal Engine のプラグインはコードとデータのコレクションで、デベロッパーがプロジェクトごとにエディタで簡単に有効化 / 無効化できます。プラグインは、ランタイムゲームプレイ機能の追加、エンジンのビルトイン機能の変更や新規追加、新しいファイルタイプの作成、そして新しいメニュー、ツールバーコマンド、サブモードでエディタ機能の拡張を行います。既存の UE4 サブシステムの多くは、プラグインを使用して拡張できるように設計されています。

すぐにプラグインを作成したい場合は「新しいプラグインを作成する」セクションを参照してください。

エディタのプラグイン UI

[Edit (編集)] メニューから [Plugin Editing Interface (プラグイン編集インターフェース)] を開くと、現在インストール済みのプラグインを確認できます。

メイン画面の ['Window' (ウィンドウ)] メニューからプラグインエディタにアクセスできます。このインターフェースは現在インストール済みのプラグインをすべて表示し、ここでプラグインを個別に有効化/無効化できます。

左側のツリー型インターフェースを使用してプラグインのカテゴリを参照できます。カテゴリを選択すると、そのカテゴリのプラグインとサブカテゴリのプラグインをすべて表示します。カテゴリを移動する場合は UI の上部に表示されるブレッドクラムリストを使用して、より高いレベルのカテゴリにすばやく移動できます。カテゴリの横に表示される数字は、そのカテゴリの使用できるプラグインの数を表します。

プラグインはメインリストに表示され、ここには各プラグインの名前、アイコン、現在のバージョン、説明のテキスト、作成者、オプションで Web ハイパーリンク、プラグインが現在有効かどうかの情報を含みます。

上部の検索コントロールを使用すると、リストに表示されたプラグインを名前で検索できます。

プラグインの説明の下にある [Enabled (有効化)] チェックボックスを切り替えて、アクティブなプロジェクトで使用するプラグインを有効化 / 無効化できます。この変更を反映するにはエディタの再起動が必要な場合があります。

プラグインのアナトミー

コード付きのプラグインには「Source」フォルダがあります。このフォルダは、プラグインのモジュールソースコードを含む 1 つ以上のディレクトリを含みます。プラグインの多くはコードを含みますが、これは実際の所必須ではないことに注意してください。詳細は、プラグインのコードセクションをご覧ください。

コード付きプラグインには、そのプラグインにコンパイルされたコードを含む「Binaries」フォルダがあり、一時的なビルド製品ファイルは、プラグインディレクトリの下の「Intermediate」フォルダに別途ストアされます。

プラグインは、そのプラグイン特有のアセットファイルを含む独自のコンテンツフォルダを持つことができます。詳細は、プラグインのコンテンツのセクションをご覧ください。プラグイン構成ファイルは、他の構成ファイルと同じルールに則って配置する必要があります。

エンジンのプラグイン： [PluginName]/Config/Base[PluginName].ini
ゲームのプラグイン： [PluginName]/Config/Default[PluginName].ini

プラグインは、自分の派生データキャッシュの配布をサポートしません。

プラグインフォルダ

プラグインを見つけられるようにするには、プロジェクトまたはエンジン自体のいずれかで、プラグインの検索パスの 1 つにプラグインを配置する必要があります。

プラグインのタイプ	検索パス
Engine	`[Unreal Engine Root Directory]/Engine/Plugins/[Plugin Name]/`
Game	`[Project Root Directory]/Plugins/[Plugin Name]/`

また、プラグインを基本プラグインフォルダ配下のサブディレクトリに整理することもできます。エンジンは、プラグインを読み込む基本プラグインフォルダ配下の、すべてのサブフォルダをスキャンします。ただし、すでに見つかったプラグインのサブディレクトリはスキャンしません。

Unreal Engine は、ディスク上の「.uplugin」ファイルを検索してプラグインを見つけます。これらのファイルを 「Plugin Descriptors (プラグイン記述子)」 と呼びます。これらはプラグインに関する基本情報を提供するテキストファイルです。プラグイン記述子はプログラムを実行するたびに、エンジン、エディタ、UnrealBuildTool (UBT) から自動的に検出されロードされます。プラグインの記述子のセクションをご覧いただくと、こうしたファイルの作成とカスタマイズの方法について学習することができます。

プラグインのコード

Visual Studio や Xcode のプロジェクトファイルを生成する場合、「Source」フォルダ (「`.Build.cs」ファイルを含む) を持つプラグインがプロジェクトファイルに追加されるため、ソースコードに簡単に移動できます。これらのプラグインは、ゲームプロジェクトのコンパイル時に UBT が自動的にコンパイルします。

プラグインは、モジュールソースディレクトリを任意の数持つことができます。ほとんどのプラグインにはモジュールが 1 つしかありませんが、たとえばプラグインにエディタのみの機能やゲーム中に実行する他のコードを含める場合など、複数作成することも可能です。

プラグインのソースファイルのレイアウトは、ほとんどの部分でエンジンの他の C++ モジュールと同じです。

プラグインは、モジュールの「Source」ディレクトリ (もしくはそのサブディレクトリの 1 つ) のヘッダファイルで、UCLASS、USTRUCT など新しい Reflected Type (反射型) を宣言できます。エンジンのビルドシステムがこれらのファイルを検出し、必要に応じてコードを生成して新しい型をサポートします。モジュールのソースファイルの 1 つにあるモジュールの「generated.inl」ファイルや生成したヘッダファイルを含めるなど、C++ モジュールで UObjects を使用する通常のルールに従う必要があります。

Unreal Engine は相互依存性のあるモジュールやプラグインをサポートします。「.uproject」ファイルでプラグインを有効化すると、プロジェクトモジュールがプラグインに依存します。同様に、プラグインは独自の「.uplugin」ファイルで他のプラグインを有効化することで依存関係を示します。しかし、重要な制限が 1 つあります。それは、プラグインとモジュールは階層レベルに分かれるため、同じ階層以上のプラグインやモジュールにのみ依存できるということです。たとえば、プロジェクトモジュールはエンジンモジュールに依存できますが、エンジンモジュールはプロジェクトモジュールに依存できません。これは、エンジンとそのプラグインとモジュールすべては、プロジェクトなしでビルド可能である必要があることから、どのプロジェクトよりも高いレベルとなっているためです。次の図は、プロジェクトやモジュール間の依存関係レベルの階層を示しています。

矢印は可能な依存関係を示しています。各プラグインやモジュールの型は、自分と同じレベル以上の他の型に依存することが可能です。

エンジンのプラグイン

Unreal Engine には Engine ディレクトリ配下にビルトインプラグインがいくつかあります。エンジンのプラグインは、すべてのプロジェクトで使用できること以外はプロジェクトプラグインと同じです。通常、これらのプラグインはエンジンやツールのプログラマによって作成され、単一の場所で保持されながら複数のプロジェクトで使用できるベースラインの機能を提供します。これにより、ユーザーはエンジンコードを変更することなくエンジンの機能の追加やオーバーライドが可能です。

プラグインのコンテンツ

Unreal Engine は、ゲームのコンテンツとバイナリコードを含むプラグインをサポートしています。プラグインでコンテンツを使用するには、プラグイン記述子の anContainContent 設定を「true」にする必要があります。

プロジェクトのプラグイン

プラグインは、プロジェクトのディレクトリの「Plugins」サブフォルダ配下にあり、エンジンやエディタの起動時に検出およびロードされます。

プラグインが「Source」フォルダ (および「.Build.cs」ファイル) を含むモジュールを含む場合、生成された C++ プロジェクトファイルにプラグインコードが自動的に追加され、プロジェクトと同時にプラグインの開発にも取り組むことができます。プロジェクトをコンパイルするときに、ソースを利用できるプラグインも毎回ゲームの依存関係に従ってコンパイルされます。

「Source」フォルダがないプラグインは、プロジェクトジェネレータから無視され、C++ プロジェクトファイルに表示されません。ただし、バイナリファイルが存在する限り起動時に読み込まれます。

現時点で、プラグインのコンフィギュレーションファイルはプロジェクトにパッケージ化されません。これは将来サポートされる可能性がありますが、現在はファイルをプロジェクトの「Config」フォルダに手動でコピーする必要があります。

プラグインを Epic Marketplace で配布する

プラグインをパッケージ化するには Package... リンクをクリックして、配布するフォルダにプラグインをパッケージ化します。

プラグインのプリコンパイル

UE 5.2 用にプラグインをプリコンパイルする場合は、UE 5.2 用の Visual Studio の最小サポートバージョンである Visual Studio 2019 でプラグインをコンパイルしてください。Visual Studio 2019 でコンパイルすると、結果のライブラリがすべてのユーザーで UE 5.2 と互換性があることが保証されます。Visual Studio と Unreal Engine のバージョンの互換性についての詳細は、「Setting Up 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] が 1 つあり、これは構造で唯一の必須フィールドです。[FileVersion] はプラグイン記述子ファイルのバージョンを意味し、通常はエンジンが許可する一番高いバージョンに設定する必要があります (現在、これは「3」です)。これはプラグイン自体ではなく、プラグイン記述子ファイルの形式のバージョンです。そして頻繁に変更すべきものではなく、プラグインのリリース以降は変更できません。エンジンの古いバージョンとの互換性を最大限維持するために、古い番号のバージョンを使用することもできますが、これは推奨されません。

その他のサポートするフィールドの詳細は、 API リファレンスページを参照してください。

ブール変数のフィールド名は、変数名から頭の「b」を取り除きます。たとえば、変数 bEnabledByDefault は [EnabledByDefault] フィールドに対応します。

モジュール記述子

コードを含むプラグインの場合、記述子ファイルの [Modules (モジュール)] フィールドは少なくとも 1 つのエントリを含みます。エントリの例を以下に示します。

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

各エントリは [Name (名前)] フィールドと [Type (タイプ)] フィールドが必須です。[Name (名前)] は、プラグインと一緒にロードするプラグインモジュールの一意の名前です。ランタイム時にエンジンは、指定したモジュール名の適切なプラグインバイナリが、プラグインの「Binaries」フォルダに存在するものとして動作します。「Source」ディレクトリを持つモジュールの場は、対応する「.Build.cs」ファイルがモジュールのサブフォルダツリーに大抵存在します。[Type (タイプ)] は、モジュールのタイプを設定します。有効なオプションは Runtime、RuntimeNoCommandlet、Developer、Editor、EditorNoCommandlet、および Program です。このタイプは、モジュールをロードできるアプリケーションのタイプを決定します。たとえば、一部のプラグインはエディタが起動している時にのみロードするモジュールを含みます。ランタイムモジュールは、出荷済みのゲームであっても、すべての場合でロードされます。デベロッパーモジュールは、開発ランタイムまたはエディタビルドでのみロードされ、出荷ビルドではロードされません。エディタモジュールは、エディタの起動時にのみロードされます。プラグインは、異なるタイプのモジュールを組み合わせて使用できます。

その他のサポートするフィールドの詳細は、 API リファレンスページを参照してください。

アイコン

記述子ファイルに加えて、プラグインにはエディタのプラグインブラウザに表示するアイコンが必要です。この画像は「Icon128.png」と呼ばれる 128x128 の「.png」ファイルであり、プラグインの「/Resources/」ディレクトリに保存する必要があります。

新しいプラグインを作成する

新しいプラグインを作成するには、エディタでプラグインブラウザの [New Plugin (新しいプラグイン)] ボタンを使用します。

そして作成するプラグインのタイプを選択し、名前を入力して、基本的なパラメータをいくつか設定できます。

これで新しいプラグインがプラグインブラウザに表示され、現在のプロジェクトで有効になります。