Version: 2023.1
言語: 日本語
プラグイン
マネージプラグイン

プラグインのインポートと設定

マネージプラグイン または ネイティブプラグイン があれば、それを Unity にインポートして設定することができます。エディター内では、プラグインはスクリプトと同様にアセットとして扱われ、Inspector ウィンドウで設定することができます。

プラグイン設定を使用して、プラグインを実行する場所 (どのプラットフォーム、プラットフォームの設定、その条件など) を指定できます。

プラグインのインポート

プラグインをプロジェクトにインポートする最も簡単な方法は、プラグインをクリックして Assets フォルダーまたはそのサブフォルダーの 1 つにドラッグすることです。Unity は、特定のファイルやフォルダータイプをプラグインとして認識します。また、プラグインが意図するプラットフォームに合わせたデフォルトの設定を適用します。

対応するプラグインのファイルとフォルダーの種類

Unity では、以下の拡張子のファイルをプラグインとして扱います。

  • a
  • .aar
  • .bc
  • .c
  • .cc
  • .cpp
  • .dll
  • .def
  • .dylib
  • .h
  • .jar
  • .jslib
  • .jspre
  • .m
  • .mm
  • .prx
  • .rpl
  • .so
  • .sprx
  • .suprx
  • .swift
  • .winmd
  • .xex
  • .xib

また、Unity は特定のフォルダーをバンドルされたプラグインとして扱います。Unity はこれらのフォルダー内で追加のプラグインファイルを探しません。そのため、フォルダー内のすべてが 1 つのプラグインとみなされます。Unity は、以下の拡張子を持つフォルダーをバンドルプラグインとして扱います。

  • .androidlib
  • .bundle
  • .framework
  • .plugin

プラグインのデフォルト設定

Unity は、Assets フォルダー内のプラグインのパスがプラットフォーム固有のパターンに一致する場合、プラットフォーム固有のデフォルト設定をプラグインに自動的に適用します。パスがどのパターンにもマッチしない場合、Unity はエディタープラットフォームのデフォルト設定をプラグインに適用します。

以下の表は、Unity が認識するパスパターンを示しています。角かっこ内に表示されているパスの部分は任意です。パスにダブルドットが含まれている場合は、他のフォルダーを含むことができます。

フォルダーのパスパターン デフォルト設定
Assets/../Editor/(x86x86_64、x64) プラットフォーム: エディターのみ

CPU (任意)。サブフォルダーがある場合はそれに基づきます。
Assets/../Plugins/(x86_64x86、x64) プラットフォーム: Windows、Linux、macOS

CPU (任意)。サブフォルダーがある場合はそれに基づきます。
Assets/Plugins/iOS プラットフォーム: iOS
Assets/Plugins/WSA/(SDK80SDK81PhoneSDK81)/(x86ARM) プラットフォーム: Universal Windows Platform

SDK (任意)。サブフォルダーがある場合は、それに基づきます。互換性の理由から、SDK81 は Win81、PhoneSDK81 は WindowsPhone81 です。

CPU (任意)。サブフォルダーがある場合は、それに基づきます。

ノート: キーワード WSA の代わりに Metro を使用することができます。

プラグイン設定の変更

Unityでは、プラグインは マネージ または ネイティブ のいずれかです。以下の表は、プラグインの種類ごとにどの設定が関連するかを示しています。

設定 マネージ ネイティブ
Select platforms for plugin x x
Platform settings x x
Asset Labels x x
Asset Bundles x x
General x
Define Constraints x
Plugin load settings x

Inspector でプラグインの設定を表示変更するには、 Project ウィンドウでプラグインファイルを選択します。

マネージプラグイン (左) とネイティブプラグイン (右) の設定。
マネージプラグイン (左) とネイティブプラグイン (右) の設定。

プラグインの共通設定

Select platform for pluginPlatform settings は、Unity がどのビルドにプラグインを加えるかを指定します。

以下の表では、共通の設定項目について説明しています。

設定 Options ノート
Select platforms for plugin Editor: 再生モード用と、編集時に実行するすべてのスクリプト用。
Standalone: Windows、Linux、macOS
• Android、iOS、WebGL など、Unity のインストールに含まれるあらゆるプラットフォーム。
Unity にまだ含まれていないプラットフォームでプラグインを動作させるには、 Any Platform をチェックします。サポートしていないプラットフォームは、個別に除外することができます。

プラグインをインポートすると、Unity はそれをメモリにロードします。ネイティブのプラグインはアンロードすることができず、設定を変更しても Unity セッションにロードされたままになります。プラグインをアンロードするには、Unity を再起動する必要があります。
Platform settings 選択したプラットフォームごとに、CPU アーキテクチャや依存関係などの追加条件を指定できます。Unity は、プラットフォーム、可能な場合は、そのプラットフォーム上の特定のプラグインタイプに適用される設定のみを表示します。例えば、拡張子が.dll のネイティブプラグインファイルは、Windows上でのみ動作します。そのため、Unity は Windows の設定のみを表示します。
Editor • CPU アーキテクチャ
• OS
ほとんどのマネージプラグインはどの CPU と OS とも互換性があります。

大抵のネイティブプラグインは通常、1 つの OS のみと互換性があり、コンパイルされた方法に応じて、1 つのみの CPU アーキテクチャと互換性があります。
Windows、Linux、macOS • CPU アーキテクチャ
• OS
マネージライブラリは通常、特定のシステム API にアクセスしない限り、どの OS や CPU とも互換性があります。

ネイティブライブラリは、1 つの OS にのみ互換性がありますが、32 ビット、64 ビット、または両方の CPU アーキテクチャと互換性があります。
Universal Windows Platform ユニバーサル Windows プラットフォーム: IL2CPP スクリプティングバックエンド上のプラグイン.
Android CPU アーキテクチャ CPU アーキテクチャは、ライブラリがコンパイルされたアーキテクチャと一致している必要があります。Unity は設定を検証しません。

AAR プラグインと Android ライブラリ を参照してください。
iOS and tvOS • Framework dependencies
• Add to Embedded Binaries
• Compile flags
Add to Embedded Binaries オプションを選択すると、Unity は、最終的なアプリケーションパッケージにプラグインファイルをコピーするように、Xcode プロジェクトのオプションを設定します。これは以下の場合に行います。
• 動的にロードされたライブラリを含むバンドルとフレームワーク
• ランタイムにロードする必要のあるアセットとリソース。

Compile Flags フィールドで、Unity がビルドの一部としてコンパイルする必要があるプラグインソースコードファイルのコンパイルフラグを設定します。

ヒント: その他の一般的な設定については、アセットバンドル および エディターの検索 を参照してください。

マネージプラグインの設定

マネージプラグインでは、プロジェクトに加えたいサードパーティのライブラリやユーザーがコンパイルしたアセンブリが可能です。

General - Auto Reference

Auto Reference 設定は、プロジェクトのアセンブリ定義がプラグインファイルを参照する方法を制御します。自動参照を有効にすると、すべての定義済みのアセンブリとアセンブリ定義が自動的にプラグインファイルを参照します。

Auto Reference はフォルトで有効になっています。

プラグインを参照できるスコープを制限するには、Auto Reference を無効にします。その場合、そのプラグインへのすべての参照を明示的に宣言する必要があります。以下のような場合には、これを行うとよいでしょう。

  • スクリプトがプラグインを誤って使用することを防ぎたい。
  • プラグインを反復していて、コンパイル時間を短縮したいと考えています。プラグインを明示的に宣言する場合、Unity はプロジェクト全体ではなく、依存するアセンブリのみを再コンパイルします。
  • Asset Store のパッケージ で使用されているプラグインが、そのパッケージがインポートされているプロジェクトの他のコードと競合するのを防ぎたい場合。

Auto Reference のチェックを外すと、Unity がプロジェクト用に作成した事前定義されたアセンブリからプラグインを参照することができません。これらの事前定義されたアセンブリには、アセンブリ定義ファイルを使用して別のアセンブリに割り当てられていないプロジェクト内のすべてのスクリプトが含まれます。Auto Reference プロパティが無効になっているプラグインからクラス、関数、またはその他のリソースを参照するには、参照コードがアセンブリ定義ファイルで作成されたアセンブリに含まれている必要があります。例えば、プロジェクト内の一連のスクリプトがプラグインを使用している場合、それらのスクリプトのアセンブリ定義ファイルを作成し、定義ファイル内のプラグインへの明示的な参照を追加する必要があります。

複数のアセンブリがプラグインを使用できますが、すべてのアセンブリが依存関係を明示的に宣言する必要があります。Unity のアセンブリ定義についての詳細は、アセンブリ定義 を参照してください。

ノート: Auto Reference オプションは、ファイルがビルドに含まれるかには影響しません。プラグインのビルド設定を制御するには、Platform settings を使用します。

General - Validate Reference

Unityでは、プラグインの参照がプロジェクト内で利用可能かどうかを確認することができます。この検証を行わないと、欠落した参照が使用されそうになると、ランタイムエラーが発生する可能性があります。

Validate References オプションを有効にして確認します。

  • プラグインの参照が存在するかどうか。例えば、プラグインが Newtonsoft.Json.dll というプラグインを参照するときに、Newtonsoft.Json.dll が見つからない場合、Unity はエラーを表示します。
  • 厳密な名前の参照をロードできるかどうか。厳密な名前の参照はバージョンと一致する必要があるため、これは重要です。例えば、“b.dll” のバージョン 2.0.0 を参照しているプラグインをコンパイルする場合、そのバージョンがプロジェクトに含まれていなければなりません。

厳密な名前の参照は確認したくないが、参照が存在することはチェックしたい場合。

  1. Plugin Inspector で、Validate References を有効にします。
  2. Project Settings > Player > Other SettingsAssembly Version Validation を無効にします。

制約を定義

プラグインを Unity のメモリにロードして参照する条件を指定することができます。これらの条件は、満たさなければならないシンボル、つまり定義済みか未定義か、を意味します。

制約は、C# の #if プリプロセッサーディレクティブのように動作しますが、スクリプトレベルではなくアセンブリレベルで動作します。制約については、Assembly Definition のプロパティ で詳しく説明しています。

Unity のビルトインの定義シンボルを使用したり、Project Settings > Player > Other Settings > Script Compilation > Scripting Define Symbols でシンボルを追加することもできます。追加するシンボルは、プラットフォームごとに異なります。そのため、関連するプラットフォームごとに定義する必要があります。ビルトインシンボルのリストなど、詳細は プラットフォーム依存のコンパイル を参照してください。

ヒント: シンボルが未定義であることを指定するには、そのシンボルの前に否定の ! (エクスクラメーションマーク) を付けます。

以下の例では、Unity 2018.3 以降の非 IL2CPP スクリプティングランタイムでのみ、Unity がプラグインをロードして参照するようにします。そのためには 2 つの制約を定義し、両方とも満たす必要があります。

  • ENABLE_IL2CPP は未定義。
  • UNITY_2018_3_OR_NEWER は定義されています。
特定のランタイムと Unity のバージョンに合わせた Define Constraints
特定のランタイムと Unity のバージョンに合わせた Define Constraints

Plugin load settings - Load on startup

グラフィックスの初期化、スクリプト、アセットのロード、シーンなどに依存しないネイティブコードの実行を開始できます。これは、プレイヤーがネイティブプラグインをロードするデフォルトの方法とは異なり、通常、スクリプトによって実行されるプラグイン関数の 1 つが最初に呼び出されるまで待機します。

アプリケーションがスクリプトを実行する前にプラグインをロードするには以下を行います。

  1. UnityPluginLoad をプラグインに実装します。低レベルのネイティブプラグインインタフェース を参照してください。
  2. エディターで、Plugin load settings > Load on startup を選択します。

ヒント: プラグイン関数を呼び出す C# スクリプトの例については、ネイティブプラグイン を参照してください。

プラグイン
マネージプラグイン