Language:
Page Info
Engine Version:

プラグイン

このページでは、アンリアル エンジンのツールとランタイムに使用する独自のプラグインの開発方法について説明します。

多くのアンリアル エンジンのサブシステムは拡張可能に設計されており、全く新しい機能を追加したり、 直接エンジン コードを修正することなく、ビルトインの機能を修正できます。新規ファイル タイプの作成、 新規メニュー アイテムやツールバー コマンドのエディタへの追加、または全く新しい機能やエディタのサブモードを追加することさえできます。

今すぐプラグインをお試しになりたい場合は、プラグインの例 をご覧ください。

プラグイン エディタ UI

現在、どのプラグインがインストールされているかを調べるには、[Edit (編集)] メニューから [Plugins (プラグイン)] 編集インターフェイスを開きます。

PluginsEditor.png

プラグイン エディタは、メインの [Window] メニューからアクセスできます。このインターフェイスは、現在 インストールされているすべてのプラグインを表示し、プラグインを個々に有効化、無効化することができます。

左側の 3 つのインターフェイスを使用してプラグインのカテゴリをブラウズできます。カテゴリを選択すると カテゴリ内のすべてのプラグインだけでなく、サブカテゴリがあればそれも表示されます。カテゴリを移動すると、UI の一番上に「ブレッドクラム」トレイル (パンくずリスト) が表示され、 より高いレベルのカテゴリに迅速にジャンプすることができます。カテゴリの隣に表示される番号は、 そのカテゴリで利用可能なプラグイン数を示しています。

PluginCategories.png

プラグインはメイン リストに表示されており、その名前、アイコン、現在のバージョン、役立つ説明、作成者 (オプションでウェブのハイパーリンク)、 さらに現在プラグインが有効になっているか否かも合わせて表示されます。

一番上の検索コントロールでは、リストに表示されるプラグインを名前で検索することができます。

SearchingPlugins.png

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

プラグインのアナトミー

コードがあるプラグインはソース フォルダを持ちます。このフォルダには、プラグインのモジュールのソース コードがある 1 つ以上のディレクトリが含まれます。プラグインは多くの場合、コードを含みますが、必ずしもコードを含む必要はありません。詳細は、プラグインのコード セクション をご覧ください。

コード モジュールがあるプラグインでは、プラグインに対してコンパイルされたコードを含む独自のバイナリ フォルダを持ちます。 また、一時ビルド プロダクト ファイルはプラグイン ディレクトリの下の中間フォルダに格納されます。

プラグインは、プラグイン固有のアセット ファイルを含む独自のコンテンツ フォルダを持つことがあります。詳細は、プラグインのコンテンツ セクション をご覧ください。

プラグインはまだ config ファイルをサポートしていないことにご注意ください。将来的には追加を検討しています。

プラグインは派生データのキャッシュ (DDC) の配布もまだサポートしていないことにご注意ください。今後の追加を検討している 項目です。

プラグイン フォルダ

プラグインは常にプラグインのディレクトリにあります。プラグインが見つかるようにするには、アンリアル エンジンのプラグインの 有効な検索パスの 1 つに配置されなければなりません。

プラグイン タイプ

検索パス

Engine

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

Game

/My Project/Plugins/My Game Plugin/

基準となる Plugins フォルダ配下でプラグインをサブディレクトリに構成することもできます。エンジンはプラグインをロードするために基準となるプラグイン フォルダ配下のすべてのサブフォルダをスキャンします。 しかし、プラグインが既に見つかった場所よりも下のサブディレクトリのスキャンは行いません。

アンリアル エンジンは、ディスクの .uplugin ファイルを検索してプラグインを見つけます。こうしたファイルをプラグイン記述子と呼びます。これらはテキスト ファイルであり、 プラグインに関する基本情報を提供します。アンリアル エンジン、アンリアル エディタ、アンリアル ビルド ツールなどこうしたプログラムが実行される場所で、 プラグイン記述子は自動的に見つけられ読み込まれます。プラグインの記述子ファイル のセクションをご覧いただくと、 こうしたファイルの作成とカスタマイズの方法について学習することができます。

プラグインのコード

Visual Studio または Xcode でプロジェクト ファイルを生成すると、ソース フォルダを持つプラグインは、 プロジェクト ファイルに追加され、そのソース コードにより簡単に移動することができるようになります。こうしたプラグインはゲーム プロジェクトをコンパイルする場合に、 アンリアル ビルド ツールによって自動的にコンパイルされます。

プラグインは、任意の数のモジュールのソース ディレクトリを持つことができます。ほとんどのプラグインは 1 つだけモジュールを持ちますが、 複数のモジュールを作ることも可能です。例えば、エディタだけでコンパイルされるように設計されたいくつかの機能を持ち、 他のコードはランタイムのゲームで必要になる場合があります。

ほとんどの場合、プラグインのソース ファイルのレイアウトは、アンリアル エンジンの他の C++ モジュールと同じになります。

プラグインは、新しい UObject 型 (UCLASS, USTRUCT, など) を、モジュールのコード フォルダにあるクラスのサブディレクトリでヘッダー ファイルで宣言することを 認められています。アンリアル エンジンのビルド システムは、こうしたファイルを検出し、こうした UObjects をサポートするために必要に応じてコードを生成します。C++ モジュール内で UObjects を使用するための通常のルールに従う必要があります。 例えば、生成されたヘッダー ファイルとモジュールの generated.inl ファイルをモジュールのソース ファイルのひとつに含むなどがあります。

プラグイン モジュールで若干異なるのは、Public ソース ファイルのヘッダーです。ほとんどのプラグイン モジュールは、 Public ソース フォルダにあるヘッダー ファイルでパブリック API をエクスポートする権利はありません。これは、エンジンやゲームのコードによって 直接的な依存関係 (静的にリンク) がないからです。そのため、通常 Public ソース フォルダは空です。このルールには以下のようにいくつかの例外があります。

  • プラグインに複数の C++ モジュールがある場合、Public フォルダにあるコードはプラグイン内のモジュール間で共有できます。

  • ゲームのプラグイン (エンジンのプラグインではなく) を作成している場合で、 プラグイン モジュールのひとつとゲームを静的にリンクできるようにしたい場合。これは、プラグインの概念から少し外れますが、ゲーム クラスが継承できる、または直接使用できる新しい UObject 型を宣言するプラグインで 多くの場合役立ちます。エンジン自体はプラグインに依存関係はありません。 しかし、ゲーム プロジェクトのコードとコンテンツは直接的な依存関係を持つことがあります。

  • ゲームコードまたはその他のプラグインが、プラグイン モジュールで実装されている型にアクセスするために パブリック インターフェイスのヘッダーをプラグインと共に配布したい場合。これは滅多にないことであり、一般的にお勧めしません。 現時点では、他のプラグインに直接依存するプラグインをサポートするつもりはないからです。

プラグインのコンテンツ

アンリアル エンジンでは、バイナリ コードだけではなく、コンテンツを含むプラグインをサポートしています。この機能は現在、作業進行中です。

プラグインでコンテンツを使用するには、プラグイン記述子内の 'CanContainContent' 設定を 'true' に設定しなければなりません。プラグイン内のコンテンツは 現在開発中の機能であり、まだ使用はお勧めしません。詳しい情報は後でご利用いただけるようになるでしょう。

配布されるプラグインにコンテンツを含むことができるようにサポートするつもりです。この機能はまだ完全には実装されていないため、 まだ使用はお勧めしません。

ゲーム プロジェクトのプラグイン

プラグインは、ゲーム プロジェクトのディレクトリにある「Plugins」サブフォルダに入っていて、ゲーム エンジンとエディタを起動すると検出され、ロードされます。

プラグインにソース フォルダ (および *.Build.cs ファイル) を持つモジュールが含まれる場合、生成された C++ プロジェクト ファイルにプラグインコードが自動的に追加され、 ゲームプロジェクトと平行してプラグインを簡単に開発できるようになります。通常どおりゲーム プロジェクトをコンパイルします。 ゲーム プロジェクトをコンパイルすると、ソースを利用可能なプラグインもゲームに総合的に依存関係があるものとしてコンパイルされます。

ソースのサブフォルダを持たないプラグインはプロジェクト ジェネレータによって無視され、C++ のプロジェクト ファイルには表示されませんが、 バイナリ ファイルが存在する限りゲームの起動時には読み込まれます。

エンジンのプラグイン

アンリアル エンジンでは、Engine ディレクトリにいくつかのビルトイン プラグインがあります。エンジンのプラグインはゲーム プロジェクトのものと同様ですが、 すべてのゲーム プロジェクトで利用できるという点が異なります。通常、こうしたプラグインはエンジンとツールのプログラマによって作成され、 プラグインのような方法でベースラインの機能を実現します。これにより、エンジンのコードをひとつも修正することなく、 エンジン機能の全体を取り除いたり、オーバーライドすることができます。

デフォルトでエンジンのプラグインはゲーム モジュールやゲーム プロジェクトのプラグインのロード前にロードされます。

エンジンのプラグインには以下のような特別な要件があります。エンジンのコード モジュールは、エンジンのプラグイン モジュール ライブラリとは決して静的にリンクしてはいけません。 つまり、エンジンのプラグインはエンジンそのものからは区分されたままでなければなりません。 プラグイン モジュールは「依存関係のあるモジュール」になってはいけません。これは高度な選択肢であり、プラグインがロードできないときでもエンジンが機能できるようにするものです。

プラグインを配布する

以下はプラグインを配布するために必要な手順です。

  1. プラグインの記述子ファイル (.uplugin ファイル) を編集し、プラグインの名前、モジュール、バージョン、その他の設定を必要に応じて設定します。

  2. エディタのプラグイン ブラウザで対象のプラグインを見つけたら、 'Edit...' リンクをクリックしてプラグインに関連したメタデータ (description, ドキュメントへのリンクなど) を更新します。

  3. 'Package...' リンクをクリックして、配布用フォルダへプラグインをパックします。

デフォルトでは、ソースコード、バイナリ、コンテンツだけがプラグインでパッケージ化されます。さらにインクルードするファイルがある場合、 プラグイン フォルダの中に Config/FilterPlugin.ini という名前のファイルを作り、その中にインクルードする追加パスをこのように表示します。

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

重要注意事項:

  • コンテンツがあるプラグインでは、派生データを生成してプラグインに含めて、 エンド ユーザーがオンデマンドで生成する必要をなくすようにしたいかもしれません。この機能はまだ利用できませんが、将来追加予定です。お待ちください。

  • 配布されるプラグインには、今のところ使用許諾契約書またはその他のドキュメンテーションはまだ含まれていません。今後、対応するかもしれません。

プラグインの記述子ファイル

プラグインの記述子は、.uplugin 拡張子で終わるファイルです。ファイル名の最初の部分は常にプラグインの名前になります。 プラグインの記述子ファイルは常にプラグインのディレクトリにあり、エンジンが起動時にその場所で見つけます。

プラグインの記述子は Json (JavaScript Object Notation ) ファイル形式になっています。

記述子ファイルの例

この例のプラグイン記述子は、上の UObjectPluginダウンロード可能な例 からのものです。

{
    "FileVersion" :3,

    "FriendlyName" :"UObject Example Plugin",
    "Version" :1,
    "FriendlyVersion" :"1.0",
    "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" :"Programming Examples.Plugins",

    "Modules" :
    [
        {
            "Name" :"UObjectPlugin",
            "Type" :"Developer"
        }
    ]
}

記述子ファイル形式

フィールド名

情報

説明

FileVersion

必須

プラグインの記述子ファイル自体のバージョン。新規機能がプラグインに追加されると、後方互換性のために使用されます。通常、これは使用しているエンジンのバージョンで認められる最新バージョンに設定します。最新バージョンは現在 3 であり、ここで文書化されているフォーマットのバージョンです。このバージョンが頻繁に変更されることはないでしょう。ソース コードで、EProjectDescriptorVersion を見て実際の値を確認できます。エンジンの旧バージョンに対して最高の互換性が必要ならば、その形式の古いバージョンを使用することが可能ですが、推奨はしません。

Version

任意

プラグインのこのビルドの最新バージョン番号。この値は、将来的なバージョンで常に増えます。バージョン番号は必ずしもエンド ユーザー向けに表示されません。

VersionName

任意

エディタ UI で表示されるプラグインのバージョン。これはバージョン チェックでは決して使用されず、好みに応じてどの形式でも可能です。しかし、単純な Major.Minor フォーマットをお勧めします。バージョン番号が増えたら常に VersionName を更新します。

FriendlyName

任意

エディタ UI に表示されるプラグイン名。指定しないと、この名前はデフォルトで .uplugin ファイル名になります。

Description

任意

プラグインの用途を説明するテキストのパラグラフ。エディタのプラグイン ウィンドウに表示されます。

Category

任意

これはドットで区切られたパスの特殊な文字列で、プラグインをエディタ UI のカテゴリに割り当てることができます。純粋に整理目的に限ったものです。カテゴリ パスの例としては、"Editor Features.Level Editing.Mesh Painting" があります。各カテゴリはピリオドで区切られてツリーで深い階層を表します。

CreatedBy

任意

プラグインを作成した個人名または企業名。これはプラグイン UI や他の場所に表示される場合があります。

CreatedBy

任意

プラグインを作成した個人または企業へのリンク。指定すると、エディタ UI にウェブページにブラウズできるハイパーリンクが表示されます。

DocsURL

任意

プラグインのドキュメントへのリンク。指定すると、エディタのプラグイン ブラウザにウェブページにブラウズできるハイパーリンクが表示されます。

SupportURL

Optional

プラグインのサポート ページへのリンク。指定している場合、エディタのプラグイン ブラウザに表示されます。

CanContainContent

任意

指定して、true に設定すると、プラグインのコンテンツ サポートを有効にします。デフォルト設定は false です。詳細は プラグインのコンテンツ をご覧ください。

Modules

任意

ソースコード (およびバイナリ) を含むプラグインの場合、これは起動時にロードすべきモジュールのリストになります。詳細は以下をご覧ください。

モジュール記述子

コードを含むプラグインでは、記述子ファイルには最低 1 つのモジュール記述子が含まれます。

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

フィールド名

情報

説明

Name

必須

プラグインと合わせてロードされるプラグイン モジュールの一意の名前。ランタイムにエンジンは、ここで指定したモジュール名を持つ適切なプラグイン バイナリがプラグインのバイナリ フォルダに存在すると予測します。ソース ディレクトリを持つモジュールでは、対応する *.Build.cs ファイルがモジュールのサブフォルダ ツリー内に存在することを予測します。

Type

必須

モジュールのタイプを設定します。有効なオプションは RuntimeRuntimeNoCommandletDeveloperEditorEditorNoCommandlet、および Program です。このタイプは、どのタイプのアプリケーションがプラグイン モジュールのロードに適しているかを判断します。例えば、プラグインによっては、エディタが実行している時に限りロードされるように設計されたモジュールを含む場合があります。Runtime モジュールは、出荷されたゲームであっても、すべてのケースでロードされます。Developer モジュールは開発のライタイムまたはエディタのビルドでのみロードされますが、シッピング ビルドでは決してロードされません。Editor モジュールは、エディタの起動時のみロードされます。プラグインは様々なタイプのモジュールを組み合わせて使用できます。

LoadingPhase

任意

指定すると、起動時にプラグインをいつロードするかを制御します。これは通常は必要としない高度なオプションです。有効なオプションは Default (LoadingPhase が何も指定されない場合に使用されます)、PreDefaultPostConfigInit です。PostConfigInit では、エンジンが主要なサブシステムの起動を終了する前にモジュールのロードができます。PreDefault は、通常のフェーズ前にロードします。これは通常、ゲーム モジュールをプラグイン内のコンテンツに直接依存させる場合、またはプラグインのコード内で型が宣言されている場合に限り必要になります。

WhitelistPlatforms

Optional

指定すると、このモジュールのコンパイル対象となるプラットフォームを表示します。指定しないと、モジュールはすべてのプラットフォームに対してコンパイルされます。

BlacklistPlatforms

Optional

指定すると、このモジュールのコンパイル対象となるプラットフォームを表示します。指定しないと、モジュールはすべてのプラットフォームに対してコンパイルされます。

アイコン ファイル

記述子ファイルと共に、プラグインは通常、エディタの UI にプラグインを表示する場合に使用するアイコン ファイルを持ちます。

ファイル名

情報

形式

説明

/Resources/Icon128.png

必須

128x128 PNG ファイル

このアイコンはエディタ UI でプラグインを表します。メインの [Window] メニューからアクセスできる 'Plugins' のユーザー インターフェイスに表示されます。

プラグインの例

いくつかのサンプル プラグインを作成しました。これは実際には何も行いませんが、ご自身のプラグイン作成を開始するときに使用可能な空のシェルとしての役割を果たします、サンプル プラグインはエンジンのソース コードに入っています。

サンプル名

情報

BlankPlugin

このプラグインは空のシェルであり、新規のコードのプラグイン モジュールをセットアップするために必要な最低限のファイルを示します。

UObjectPlugin

UObject クラスをどのように宣言するかを示す単純な空のプラグインです。

こうしたサンプルをプラグインの開始点として使用するには以下の手順に従います。

  1. サンプル プラグインを新規フォルダにコピーし、ディレクトリ、ファイル、およびコードのコンテンツの名前を変更し、ご自身の新規プラグイン名に合わせます。既存の名前はそのまま使用しません。エンジンに含まれるビルトインのプラグインと重なるからです。

  2. ゲーム プロジェクト ディレクトリの下に 「Plugins」フォルダ を作成し、「Plugins」の下にある任意のサブディレクトリにご自身のプラグインコピーします。 ExamplePlugins.png

  3. C++ プロジェクト ファイル を再ビルドします。プラグイン モジュールとソース コードが、プロジェクト ファイルのプロジェクト ディレクトリの下にあるディレクトリに表示されます。

  4. 通常どおり ゲーム プロジェクト をコンパイルします。アンリアルのビルド ツールは、プラグインを検知し、ゲームに依存関係があるものとしてコンパイルします。

  5. エディタ (またはゲーム) を起動します。プラグインは最初は無効になりますが、エディタの UI で有効にできます。

  6. プラグイン エディタを開きます (Window -> Plugins の順序で)。プラグインを検索し、チェック ボックスをクリックして有効にします。

  7. エディタを再起動します。プラグインは自動的に起動時にロードされます。

[Window] -> [Developer Tools] メニューで モジュール ビューアを開くとプラグインがロードされたのがわかります。 もうひとつの方法では、コード デバッガを使用して、プラグインのスタートアップ コードに、FBlankPlugin::StartupModule() などのブレークポイントを入れます。