Unity での C# コードのデバッグ
デバッガーを使用すると、アプリケーションの実行中にソースコードを検査することができます。Unity では以下のコードエディターで C# コードをデバッグできます。
- Visual Studio (Visual Studio Tools for Unity プラグインを使用)
- Visual Studio Code (Unity for Visual Studio Code Extension を使用)
- Jetbrains Rider
これらのコードエディターは、サポートするデバッグ機能がわずかに異なりますが、すべてがブレークポイント、シングルステップ、変数検査などの基本的な機能を提供します。これらのコードエディターを Unity エディター または Unity Player にアタッチしてコードをデバッグできます。
Unity のマネージコードデバッグは Web を除くすべてのプラットフォームで使用できます。Mono と IL2CPP 両方のスクリプティングバックエンドで動作します。
IDE の設定
Unity でのデバッグ用にサポートされている各 IDE の設定要件については、統合開発環境 (IDE) サポート を参照してください。
ブレークポイント
ブレークポイントを使用すると、コード内で実行を一時停止するポイントを指定できます。外部コードエディターで、デバッガーを停止するコード行にブレークポイントを設定できます。コードエディターがブレークポイントにある間、変数の内容を段階的に見ることができます。
コードエディターを Unity エディターにアタッチしている場合 (Unity エディターへのコードエディターのアタッチ を参照)、コードエディターで続行オプションを選択するかデバッグモードを停止するまで、Unity エディターは応答しません。
Visual Studio でブレークポイントを設定する方法については、Visual Studio でのブレークポイントの設定 を参照してください。
Unity エディターでのデバッグ
Unity エディターが再生モードになっている間に、Unity エディターで実行されている C# コードをデバッグすることができます。
エディターでデバッグを行うには、エディターのコード最適化モードを Debug Mode に設定し、デバッグ機能を持つコードエディターをアタッチ する必要があります。
コード最適化モードを変更するには、Unity エディターのステータスバーの右にあるデバッグボタンを選択します。
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 でこれを行う方法については、Unity エディターへの Visual Studio のアタッチ を参照してください。
コードエディターを Unity エディターにアタッチし、デバッグを開始する準備ができたら、Unity エディターに戻り再生モードを開始します。
Unity Player でのデバッグ
デバッグ用に Unity Player をコンパイルするには、以下を行います。
- File > Build Profiles に移動します。
- Player をビルドする前に、Development Build と Script Debugging のオプションを有効にします。Wait For Managed Debugger オプションを有効にして、Player がスクリプトコードを実行する前にデバッガーがアタッチされるのを待機させることもできます。
- Build And Run を選択します。
Unity Player へのコードエディターのアタッチ
コードエディターを Unity Player にアタッチするには、コードエディターで Player の IP アドレス (またはマシン名) とポートを選択します。Visual Studio でこれを確認する場所の例については、Unity エディターへの Visual Studio のアタッチ を参照してください。
ノート: コードエディターには、デバッグ可能な Unity のすべてのインスタンスが表示されます。コードエディターを Unity Player の正しいインスタンスにアタッチし、Unity エディターにアタッチしないように注意してください (両方が実行されている場合)。
デバッガーをアタッチしたら、通常どおりにデバッグを開始できます。Unity Player を特定のコードエディターにアタッチする方法については、コードエディターの外部ドキュメント を参照してください。モバイルデバイスで実行する Unity Player を Visual Studio にアタッチする方法の例については、Visual Studio による Android および iOS デバイスのデバッグ を参照してください。
Visual Studio でのブレークポイントの設定
Visual Studio でブレークポイントを設定するには、コードの左側の列で、デバッガーを停止したい行をクリックします。行番号の横に赤い円が表示され、行がハイライト表示されます。
Unity エディターへの Visual Studio のアタッチ
Unity エディターを Visual Studio スクリプトにアタッチするには、Visual Studio を開き、Debug > Attach Unity Debugger の順に移動し、デバッグする Unity エディターのインスタンスを選択します。
以下の画像の例では、エディターで実行されている Unity のインスタンスが 1 つ、Android Player として実行されている Unity のインスタンスが 1 つあります。
Visual Studio による Android および iOS デバイスのデバッグ
Android
Android デバイスで実行中に Unity Player をデバッグするには、USB または TCP を使用してデバイスに接続します。例えば、Visual Studio で Android デバイスに接続するには、Debug > Attach Unity Debugger オプションを選択します。Player インスタンスを実行しているデバイスのリストが表示されます。
この例では、Android デバイスは、USB と、Unity エディターと Visual Studio を実行するワークステーションと同じネットワーク上の Wi-Fi を使用して接続されています。
iOS
iOS デバイスで実行中に Unity Player をデバッグするには、TCP を使用してデバイスに接続します。例えば、Visual Studio for Mac で iOS デバイスに接続するには、Debug > Attach Unity Debugger を選択します。Player インスタンスを実行しているデバイスのリストが表示されます。
デバイスが 1 つのアクティブなネットワークインターフェースのみを持ち (Wi-Fi が推奨なのでモバイルデータ通信をオフにします)、IDE とデバイスの間のファイアウォールが TCP ポートをブロックしていないことを確認します (上記のスクリーンショットでポート番号 56000)。
重要: iOS は USB でのデバッグをサポートしていません。
デバッガーのトラブルシューティング
デバッガーのほとんどの問題は、コードエディターが Unity エディターや Unity Player を見つけることができないために発生します。これは、Unity エディターまたは Player がデバッガーを正しくアタッチできないことを意味します。デバッガーはエディターまたは Player への TCP 接続を使用するため、接続の問題はしばしばネットワークによって発生します。以下は、基本的な接続問題のトラブルシューティングを行うための手順です。
デバッガーを正しい Unity インスタンスに設定するよう確認する
コードエディターは、デバッグが有効になっているローカルネットワーク上のすべての Unity エディターまたは Unity Player のインスタンスにアタッチすることができます。デバッガーをアタッチするときは、正しい Unity インスタンスにアタッチしていることを確認してください。Unity Player を実行しているデバイスの IP アドレスやマシン名が分かっている場合は、正しいインスタンスを見つけるのに役立ちます。
Unity インスタンスへのネットワーク接続を確認する
コードエディターは、Unity プロファイラーと同様のメカニズムを使用して、デバッグする Unity インスタンスを見つけます。コードエディターが Unity インスタンスを見つけることができない場合は、Unity プロファイラーをそのインスタンスにアタッチしてみてください。Unity プロファイラーも Unity インスタンスを見つけることができない場合は、コードエディターまたは Unity インスタンスを実行しているマシンにファイアウォールがある可能性があります。ファイアウォールが設定されている場合は、ファイアウォールの設定を確認する を参照してください。
デバイスがアクティブなネットワークインターフェースを 1 つしか持たないように確認する
多くのデバイスは複数のネットワークインターフェースを持っています。例えば、携帯電話はアクティブなモバイル通信接続とアクティブな Wi-Fi 接続の両方がある場合があります。TCP を使用してデバッガーを Unity インスタンスに正しく接続するには、IDE がデバイスの正しいインターフェースにネットワーク接続する必要があります。例えば、Wi-Fi 経由でデバッグする場合は、デバイスを機内モードにして他のすべてのインターフェースを無効にしてから、Wi-Fi を有効にしてください。
Unity Player が 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 という名前のファイルに格納されます。
正しい Preferences とビルドオプションを有効にすると (コードエディターの設定 を参照)、Unity は自動的にこのデバッグ情報を生成します。ただし、Unity はプロジェクト内のマネージプラグインのデバッグ情報を生成することはできません。関連する .pdb ファイルがディスク上の Unity プロジェクトのマネージプラグインの隣にある場合にのみ、マネージプラグインからコードをデバッグすることが可能です。
デバイスがロックされないようにする
アプリケーションのデバッグに使用しているデバイスの画面ロックを無効にしてください。画面ロックはデバッガーが切断される原因となり、再接続を妨げます。マネージコードのデバッグ中に画面をロックしないでください。画面がロックされている場合は、デバッガーが再度接続できるように、デバイス上でアプリケーションを再起動してください。
デバッガーによるメモリおよびスレッドリーク
マネージデバッガーを実装すると、スレッドの起動と終了に関連する競合状態を処理するために、OS レベルのスレッドハンドルとスレッドに関連するメモリの一部がリークされます。実際には、これらのリークは小さく、アプリケーションのリソース使用には影響しません。ただし、多くのスレッドが作成および破棄されると、リークが顕著になります。この動作は、実際のメモリリークの追跡を難しくする可能性もあるため、メモリリークのトラブルシューティング時には、スクリプトのデバッグを無効にすることを推奨します。
コードエディターの外部ドキュメント
- Visual Studio - Using Visual Studio Tools for Unity (Windows)
- Visual Studio Code - Unity Development with VS Code
- Jetbrains Rider - Debug Unity Applications