プラグイン

Unreal Engine プラグインの作成方法。

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

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

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

エディタのプラグイン UI

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

PluginsEditor.png

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

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

PluginCategories.png

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

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

SearchingPlugins.png

プラグインの説明の下にある [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 つ) のヘッダ ファイルで、UCLASSUSTRUCT など新しい Reflected Type (反射型) を宣言できます。エンジンのビルド システムがこれらのファイルを検出し、必要に応じてコードを生成して新しい型をサポートします。モジュールのソース ファイルの 1 つにあるモジュールの「generated.inl」ファイルや生成したヘッダ ファイルを含めるなど、C++ モジュールで UObjects を使用する通常のルールに従う必要があります。

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

PluginAndModuleDependency.png

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

エンジンのプラグイン

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

プラグインのコンテンツ

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

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

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

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

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

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

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

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

PackagePlugin.png

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

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」です)。これはプラグイン自体ではなく、プラグイン記述子ファイルの形式のバージョンです。そして頻繁に変更すべきものではなく、プラグインのリリース以降は変更できません。エンジンの古いバージョンとの互換性を最大限維持するために、古い番号のバージョンを使用することもできますが、これは推奨されません。

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

bEnabledByDefault

モジュール記述子

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

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

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

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

アイコン

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

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

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

CreatePlugin.png

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

PluginTypes.png

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

タグ
このページは Unreal Engine の前のバージョン用です。現在リリースされている Unreal Engine 5.3 に対して更新は行われていません。
Unreal Engine のドキュメントを改善するために協力をお願いします!どのような改善を望んでいるかご意見をお聞かせください。
調査に参加する
キャンセル