マネージプラグイン

マネージプラグインとは、.NET アセンブリ を作成し、Visual Studio などのツールで Unity の外部でコンパイルして動的リンクライブラリ (DLL) にしたものです。

This is a different process from standard C# scripts, which Unity stores as source files in the Assets folder in your Unity project. Unity compiles standardn C# scripts whenever they change, whereas DLLs are pre-compiled and don’t change. You can add a compiled .dll file to your project and attach the classes it contains to GameObjects in the same way as standard scripts.

C# のマネージドコードの詳細については、Microsoft のマネージコードに関するドキュメント を参照してください。

マネージプラグインには .NET コードのみが含まれているため、.NET ライブラリでサポートされていない機能にアクセスできません。ただし、マネージコードは Unity がスクリプトのコンパイルに使用する標準の .NET ツールにアクセスできます。

Unity で DLL を扱う場合、スクリプトを扱う場合よりも多くのステップを完了させる必要があります。ただし、代わりに .dll ファイルを作成して Unity プロジェクトに加えることが便利な場合もあります。以下はその例です。

• Unity が対応しないコードでコンパイラーを使いたい。
• サードパーティの .NET コードを .dll ファイルに加えたい。
• Unity にソース無しでコードを供給したい。

このページでは、マネージプラグインを作成するための一般的なメソッドと、マネージプラグインの作成方法、Visual Studio を使用したデバッグセッションの設定方法について説明します。

ネイティブプラグインの作成

マネージプラグインを作成するには、DLL を作成する必要があります。これを行うには、以下のような適切なコンパイラーが必要です。

• Visual Studio
• MsBuild
• .NET SDK

.NET コードを生成するすべてのコンパイラーが Unity と互換性があるわけではありません。そのため、コンパイラーで重要な作業をする前に、利用可能ないくつかのコードでコンパイラーをテストする必要があります。DLL を作成するために使用する方法は、DLL に Unity API コードが含まれているかどうかによります。

• DLL に Unity API コードが含まれている場合、コンパイル前に Unity 自体の DLL をコンパイラーで利用可能にする必要があります。
  1. Unity の DLL を探すには以下を行います。
     • Windows の場合、C:\Program Files\Unity\Hub\Editor\<version-number>\Editor\Data\Managed\UnityEngine に移動します。
     • macOS の場合
       1. コンピューター上で Unity.app ファイルを探します。macOS の Unity DLL へのパスは、/Applications/Unity/Hub/Editor/<version-number>/Unity.app/Contents/Managed/UnityEngine です。
       2. Unity.app を右クリックします。
       3. Show Package Contents を選択します。
  2. UnityEngine フォルダーには、多くのモジュールの .dll ファイルが含まれています。スクリプトでそれらを利用可能にするために、それらを参照します。名前空間によっては、Unity プロジェクトからコンパイルされたライブラリへの参照も必要です (例えば、UnityEngine.UI)。プロジェクトフォルダーのディレクトリ ~\Library\ScriptAssemblies でこれを探します。

• DLL に Unity の API コードが含まれていない場合、または Unity の DLL をすでに利用可能にしている場合、コンパイラーのドキュメントに従って .dll ファイルをコンパイルしてください。DLL をコンパイルするための正確なオプションは、使用するコンパイラーによります。例えば、Roslyn コンパイラーのコマンドライン csc は、macOS では次のようになります。

csc /r:/Applications/Unity/Hub/Editor/<version-number>/Unity.app/Contents/Managed/UnityEngine.dll /target:library /out:MyManagedAssembly.dll /recurse:*.cs

以下の例の説明:

• /r オプションで、ビルドに加えるライブラリへのパス (ここでは、UnityEngine ライブラリ) を指定します。
• /target オプションで、必要なビルドのタイプを指定します。“library” は DLL ビルドを意味します。
• /out でライブラリ名を指定します。この場合、“MyManagedAssembly.dll” となります。
• 入れるソースファイルの名前を加えます。/recurse メソッドを使用して、現在の作業ディレクトリとサブフォルダーにある “.cs’” で終わるすべてのファイルを加えます。結果の .dll ファイルは、ソースファイルと同じフォルダーに表示されます。

マネージプラグインの使用

DLL をコンパイルしたら、他のアセットと同じように .dll ファイルを Unity プロジェクトにドラッグすることができます。すると、以下を行えます。

• マネージプラグインを展開して、ライブラリ内のそれぞれのクラスを表示。
• MonoBehaviour から派生したクラスをゲームオブジェクトにドラッグ。
• 他のスクリプトから MonoBehaviour 以外のクラスを直接使用。

Visual Studio で DLL を作成

ここでは、以下を説明します。

• Visual Studio で簡単な DLL サンプルをビルドして統合する方法
• Unity で DLL のデバッグセッションを準備する方法。

プロジェクトの設定

1. Visual Studio を起動し、新しいプロジェクトを作成します。
2. File > New > Project > Visual C# > .Net Standard > Class Library (.NET Standard) を選択します。
3. 新しいライブラリに以下の情報を入力します。
   • Name は名前空間です (この例では DLLTest という名前を使用)。
   • Location はプロジェクトの親フォルダーです。
   • Solution name はプロジェクトフォルダーです。
4. Unity DLL をスクリプトで利用できるようにします。Visual Studio の Solution Explorer で References のコンテキストメニューを開き、Add Reference > Browse > Select File を選択します。
5. UnityEngine フォルダーで、必要な .dll ファイルを選択します。

DLL のコードを作成

1. この例では、ソリューションブラウザーでデフォルトクラスを MyUtilities に名前変更します。
2. そのコードを次のように置き換えてください。

using System;   
using UnityEngine;

namespace DLLTest {

    public class MyUtilities {
    
        public int c;

        public void AddValues(int a, int b) {
            c = a + b;  
        }
    
        public static int GenerateRandom(int min, int max) {
            System.Random rand = new System.Random();
            return rand.Next(min, max);
        }
    }
}

1. プロジェクトをビルドして、DLL ファイルとそのデバッグシンボルを生成します。

Unity で DLL をデバッグ

Unity で DLL のデバッグセッションを設定するには、以下を行います。

1. Unity で新規プロジェクトを作成し、ビルドした .dll ファイル (例えば、<project folder>/bin/Debug/DLLTest.dll) を Assets フォルダーにコピーします。
2. Assets フォルダーに Test という C# スクリプトを作成します。
3. そのコンテンツを、DLL で作成したクラスの新しいインスタンスを作成し、その関数を使用し、その出力を コンソール ウィンドウに表示するスクリプトに置き換えます。例えば、上のセクションの DLL のテストスクリプトを作成するには、以下のコードをコピーしてください。

using UnityEngine;
using System.Collections;
using DLLTest;

public class Test : MonoBehaviour {

     void Start () {
        MyUtilities utils = new MyUtilities();
        utils.AddValues(2, 3);
        print("2 + 3 = " + utils.c);
     }
    
     void Update () {
        print(MyUtilities.GenerateRandom(0, 100));
     }
}

1. このスクリプトをシーンのゲームオブジェクトにアタッチして、再生ボタンをクリックします。

Unity は、DLL からのコードの出力をコンソールウィンドウに表示します。

unsafe な C# コードのコンパイル

Unsafe C# コード は、メモリに直接アクセスできるコードです。コンパイラーは、それがセキュリティリスクをもたらさないことを検証できないため、デフォルトでは有効になっていません。

以下の場合に unsafe コードを使う場合があります。

• ポインターを使用してメモリにアクセスする。
• Raw メモリを割り当てる。
• ポインターを用いてメソッドを呼び出す。

unsafe な C# コードのコンパイルに対応するには、Edit > Project Settings > Player > Other Settings の順に移動し、Allow Unsafe Code を有効にします。

詳細については、Microsoft のアンセーフコード、ポインター型、関数ポインター を参照してください。