Unity で C# コードをデバッグする
デバッガーを使用すると、アプリケーションやゲームの実行中にソースコードを検査することができます。Unity は、C# コードのデバッグのために以下のコードエディターをサポートします。
- Visual Studio (Visual Studio Tools for Unity プラグインを使用)
- Visual Studio for Mac
- Jetbrains Rider
- Visual Studio Code (実験的)
これらのコードエディターは、サポートするデバッグ機能に若干の違いがありますが、いずれもブレークポイントやシングルステップ、変数の検査といった基本的な機能を備えています。これらのコードエディターを Unity エディター または Unity プレイヤー に接続して、コードのデバッグを行うことができます。
Managed code debugging in Unity works on all platforms except Web. It works with both the Mono and IL2CPP scripting backends.
コードエディターを設定する
Visual Studio (Windows)
Unity エディターのインストーラーには、Visual Studio を Visual Studio Tools for Unity プラグイン と共にインストールするオプションがあります。これは、Unity でデバッグするために Visual Studio 設定する推奨方法です。
Visual Studio が既にコンピューターにインストールされている場合は、それを開き、Tools > Get Tools and Features… の順に移動して、Visual Studio Tools for Unity プラグインをインストールします。
Visual Studio for Mac
Unity エディターのインストーラーには、Visual Studio for Mac をインストールするためオプションが含まれています。これは Unity を使ったデバッグ用に Visual Studio for Mac を設定する推奨される方法です。
Visual Studio for Mac が既にコンピューターにインストールされている場合は、それを開き Visual Studio > Extensions > Install from file… の順に移動し、Visual Studio Tools for Unity プラグインを見つけてインストールします。
JetBrains Rider
JetBrains Rider のデフォルトのインストールを使って、Windows または Mac 上の Unity でコードをデバッグできます。インストールするには JetBrains ウェブサイト を参照してください。
Visual Studio Code
Visual Studio Code を使用して Unity でデバッグを行うには、拡張機能をインストールする必要があります。Visual Studio Code の ドキュメントを参照して、Visual Studio Code を Unity プロジェクトのコードエディターとして設定します 。Visual Studio Code の Debugger for Unity 拡張に特化した手順 に従って、インストールします。Unity は Debugger for Unity エクステンションを公式にサポートしていないため、Unity の Visual Studio Code に対する適応は実験的なものです。
Unity で外部スクリプトエディターを指定する
コードエディターをインストールしたら、Preferences > External Tools に移動し、External Script Editor で選択したコードエディターを設定します。
ブレークポイント
ブレークポイントを使用すると、コードの実行を一時停止するポイントを指定することができます。外部コードエディタでは、デバッガーを停止させたいコードの行にブレークポイントを設定することができます。コードエディターがブレークポイントを設定している場合は、変数の内容を段階的に確認することができます。
コードエディターを Unity エディターに設定している場合 (Unity エディターにコードエディターを設定 を参照)、コードエディターで継続オプションを選択するか、デバッグモードを停止するまで Unity エディターは無応答になります。
Visual Studio でブレークポイントを設定する方法については、Visual Studio でブレイクポイントを設定する を参照してください。
Unity エディターでデバッグする
Unity エディターが再生モードになっている間に、Unity エディターで実行される C# コードをデバッグすることができます。
エディターでデバッグを行うには、エディターのコード最適化モードを デバッグモード に設定し、デバッグ機能を持つコードエディターを設定 します。
コード最適化モードを変更するには、Unity Editor Status Bar の右にあるデバッグボタンを選択します。
Unity のコード最適化設定には 2 つのモードがあります。
- Debug Mode - 外部のデバッガーソフトを接続して使用することができますが、エディタのプレイモードでプロジェクトを実行すると、C#のパフォーマンスが低下します。
- Release Mode - エディターの再生モードでプロジェクトを実行すると、C# のパフォーマンスが速くなりますが、外部のデバッガーを取り付けることはできません。
ステータスバーのデバッグボタンをクリックすると、小さなポップアップウィンドウが開き、モードを切り替えるためのボタンが表示されます。また、現在のモードに関する情報や、モードを切り替えた場合の動作についても表示されます。
Unity エディターの起動時のモードを変更するには、Edit (macOS: Unity) > Preferences > General > Code Optimization On Startup の順に移動します。
これらの設定をスクリプトで制御するには、以下の API を使用します。
また、エディターの起動モードを変更したり、デバッガーのリッスンソケットをオフにすることもできます。これを行うには、エディターを起動する際に、以下の コマンドライン引数 を使用します。
-
-releaseCodeOptimizationエディターを Release コード最適化モードで起動します。 -
-debugCodeOptimizationエディターを Debug コード最適化モードで起動します。 -
-disableManagedDebuggerデバッガーのリッスンソケットを無効にして、エディターを起動します。
コードエディターを Unity エディターにアタッチする
コードエディターを Unity エディターにアタッチする方法は、使用しているコードエディターによって異なり、しばしば、コードエディターの通常のデバッグプロセスとは異なるオプションになります。コードエディターによっては、デバッグする Unity のインスタンスを選択することができます。使用するコードエディター固有の手順については、コードエディターの外部ドキュメント を参照してください。Visual Studio でこれを行う方法については、Visual Studio を Unity エディターにアタッチする を参照してください。
Unity エディターにコードエディターを設定し、デバッグを開始できる状態になったら、Unity エディターに戻り、再生モードを開始します。
Unity プレイヤーでデバッグする
デバッグ用の Unity プレイヤーをコンパイルするには以下を行います。
- File > Build Settings の順に移動します。
- プレイヤーをビルドする前に、Development Build および Script Debugging オプションを有効にします。また、Wait For Managed Debugger オプションを有効にして、プレイヤーがスクリプトコードを実行する前に、デバッガーが設定されるのをプレイヤーに待機させることもできます。
- Build And Run を選択します。
コードエディターを Unityプレイヤーにアタッチする
コードエディターを Unity プレイヤーに設定するには、コードエディターで、プレイヤーの IP アドレス (またはマシン名) とポートを選択します。Visual Studio でこれを見つける例は、Visual Studio を Unity エディターに設定する を参照してください。
ノート: コードエディターには、デバッグ可能な Unity のインスタンスがすべて表示されます。コードエディターは、(両方とも実行中の場合は、Unity エディターではなく) Unity プレイヤー の正しいインスタンスに設定するようにしてください。
デバッガーを設定すると、通常のデバッグを開始することができます。特定のコードエディターに Unity プレイヤーを設定する方法については、コードエディターの外部ドキュメント を参照してください。モバイルデバイス上で動作する Unity プレイヤーを Visual Studio に設定する方法の例は、Visual Studio で Android と iOS devices をデバッグする を参照してください。
Visual Studio でブレークポイントを設定する
Visual Studio でブレークポイントを設定するには、コードの左側の列で、デバッガーを停止させたい行をクリックします。行番号の横に赤い丸が表示され、その行がハイライトされます。
Unity エディターに Visual Studio をアタッチする
Visual Studio スクリプトに Unity エディターを設定するには、Visual Studio を開き、Debug > Attach Unity Debugger と移動し、デバッグしたい Unity エディターのインスタンスを選択します。
以下のサンプル画像では、エディターで実行中の Unity のインスタンスと、Android プレイヤーとして実行中の Unity のインスタンスが 1 つずつ存在しています。
Visual Studio で Android と iOS デバイスをデバッグする
Android
Android デバイスで実行中に Unity プレイヤーをデバッグするには、USB または TCP 経由でデバイスに接続します。例えば、Visual Studio で Android デバイスに接続するには、 Debug > Attach Unity Debugger を選択します。 プレイヤーインスタンスを実行しているデバイスのリストが表示されます。
この例では、Android 端末は、Unity エディターと Visual Studio が実行中のワークステーションと同じネットワーク上で USB と Wi-Fi を使って接続されています。
Chrome OS の Android
Unity は ChromeOS デバイスを自動検出できません。接続を開始するには、Android Debug Bridge (adb) を使用してデバイスに接続します。adb の使用方法については、Android Studioユーザーガイド を参照してください。
iOS
iOS デバイスで実行中に Unity プレイヤーをデバッグするには、TCP 経由でデバイスに接続します。例えば、Visual Studio for Mac で iOS デバイスに接続するには、 Debug > Attach Unity Debugger を選択します。 プレイヤーインスタンスを実行しているデバイスのリストが表示されます。
デバイスが 1 つのアクティブなネットワークインターフェースのみを持ち (Wi-Fi が推奨なのでモバイルデータ通信をオフにします)、IDE とデバイスの間のファイアウォールが TCP ポートをブロックしていないことを確認します (上記のスクリーンショットでポート番号 56000)。
重要: iOS は USB 経由でのデバッグをサポートしていません。
デバッガーのトラブルシューティング
デバッガーのほとんどの問題は、コードエディターが Unity エディターや Unity プレイヤーを見つけることができないために発生します。つまり、Unity エディターや Unity プレイヤーがデバッガーを正しく設定できないということです。デバッガーはエディターまたはプレイヤーへの TCP 接続を使用するため、接続の問題はしばしばネットワークによって発生します。以下は、基本的な接続問題のトラブルシューティングを行うための手順です。
デバッガーを正しい Unity インスタンスに設定するよう確認する
コードエディターは、デバッグが有効になっているローカルネットワーク上の Unity エディターまたは Unity プレイヤーのすべてのインスタンスに設定することができます。デバッガーを設定する場合は、正しい Unity インスタンスに設定していることを確認します。Unity プレイヤーを実行しているデバイスの IP アドレスやマシン名が分かっている場合は、正しいインスタンスを見つけるのに役立ちます。
Unity インスタンスへのネットワーク接続を確認する
コードエディターは、Unity プロファイラーが使用するのと同様のメカニズムを使用して、デバッグする Unity インスタンスを見つけます。コードエディターが期待する Unity インスタンスを見つけることができない場合は、Unity プロファイラーをそのインスタンスに接続してみてください。Unity プロファイラーもそれを見つけることができない場合は、コードエディターや Unity インスタンスを実行しているマシンにファイアウォールが存在する可能性があります。ファイアウォールがある場合は、以下の ファイアウォール設定を確認する を参照してください。
デバイスがアクティブなネットワークインターフェースを 1 つしか持たないように確認する
多くのデバイスは複数のネットワークインターフェースを持っています。例えば、携帯電話はアクティブなモバイル通信接続とアクティブな Wi-Fi 接続の両方がある場合があります。デバッガーを TCP を使って Unity インスタンスに正しく接続するには、IDE がデバイスの正しいインターフェースにネットワーク接続する必要があります。Wi-Fi 経由でデバッグする場合は、デバイスを機内モードにして他のすべてのインターフェースを無効にしてから、Wi-Fi を有効にしてください。
Unity プレイヤーが IDE にどの IP アドレスを使用するよう指示するかは、プレイヤーログを確認することで判断できます。以下のようなログの部分を探します。
Multi-casting "[IP] 10.0.1.152 [Port] 55000 [Flags] 3 [Guid] 2575380029 [EditorId] 4264788666 [Version] 1048832 [Id] iPhonePlayer(Example-iPhone):56000 [Debug] 1 [PackageName] iPhonePlayer" to [225.0.0.222:54997]...
このメッセージは、IDE が IP アドレス 10.0.1.152 とポート 56000 を使用してデバイスに接続しようとしていることを示しています。この IP アドレスとポートは、IDE を実行しているコンピューターからアクセス可能である必要があります。
ファイアウォールの設定を確認する
Unity インスタンスは、TCP 接続を使ってコードエディターと通信します。ほとんどの Unity プラットフォームでは、この TCP 接続は任意に選択されたポートで行われます。通常、このポートはコードエディターが自動的に検出する必要があるため、ポートを認識する必要はありません。それでもうまくいかない場合は、ネットワーク分析ツールを使用して、コードエディターを実行しているマシンや、Unity インスタンスを実行しているマシンやデバイスのうち、どのポートがブロックされているかを判断してください。ポートが見つかったら、ファイアウォールが、コードエディターを実行しているマシンのポートと Unity インスタンスを実行しているマシンの両方にアクセスできることを確認します。
マネージデバッグ情報が有効であることを確認する
デバッガーが Unity インスタンスに設定されても、ブレークポイントがロードされない場合は、デバッガーがコードのマネージデバッグ情報を見つけることができない可能性があります。マネージコードのデバッグ情報は、ディスク上のマネージアセンブリ (.dllファイル) の隣の .pdb という名前のファイルに格納されます。
正しい環境設定とビルドオプションを有効にすると (コードエディターの設定 参照)、Unity はこのデバッグ情報を自動的に生成します。ただし、Unity はプロジェクト内のマネージプラグインのデバッグ情報を生成できません。ディスク上の Unity プロジェクトで、関連する .pdb ファイルがマネージプラグインの隣にある場合にのみ、マネージプラグインのコードをデバッグできます。
デバイスのロックを避ける
アプリケーションのデバッグに使用するデバイスの画面ロックをすべて無効にします。画面ロックは、デバッガーの接続を切断し、再接続を妨げる原因となります。マネージコードのデバッグ中に画面をロックしないでください。画面がロックされた場合は、デバイス上でアプリケーションを再起動すると、デバッガーが再接続されます。
デバッガーによるメモリリークとスレッドリーク
マネージデバッガーの実装は、スレッドの起動と停止に関連するいくつかの競合状態を処理するために、OS レベルのスレッド処理とスレッドに関連する一部のメモリをリークします。実際には、これらのリークは小さく、アプリケーションのリソース負担に影響を与えることはありません。しかし、多くのスレッドが生成され破棄されると、リークが目立つようになります。このような動作は、実際のメモリーリークの追跡を困難にすることもあります。そのため、メモリーリークのトラブルシューティングを行う際には、スクリプトのデバッグを無効にすることを推奨します。
コードエディター外部ドキュメント
- Visual Studio - Visual Studio Tools for Unity を使用する
- Visual Studio for Mac - Visual Studio Tools for Unity を使用する
- Jetbrains Rider - Unityアプリケーションのデバッグ