Udonプロジェクトのデバッグ

デバッグとは、VRChat、ワールド、そしてUdonコードの内部で何が起きているのかを把握するための手段です。これはプログラミング全般において、そしてワールドを構築する上で欠かせないスキルです。

ワールドを公開する前に、VRChatでテストを行うことが重要です。ほとんどのエラーはUnityエディタ上で修正できますが、中にはVRChat内でなければデバッグできないワールドやUdonプログラムに遭遇することもあるでしょう。

VRChatのデバッグログ

エラーの特定や状況の把握を容易にするため、VRChatは訪問したワールドや発生したエラー、その他のバックグラウンド情報を記録します。これは「output log」や「デバッグログ」と呼ばれます。

VRChatのログは、VRChat内から直接確認する方法と、PC上のテキストファイルとして確認する方法があります。

1. VRChat内でログを表示する

Debug GUIを有効にしてVRChatを起動すると（下記参照）、デスクトップモードとVRモードの両方で特別なデバッグオーバーレイを表示できます。発生したログメッセージをリアルタイムで確認するには、RShift + Backtick¹ + 3 を押してください。利用可能な各種デバッグオーバーレイのショートカットについては、Keyboard and Mouseのページを参照してください。

2. テキストエディタでログを表示する

VRChatのセッション中または終了後に、ディスク内のファイルを開くことでログを確認できます。通常、ファイルは以下のフォルダに保存されています（'YourName'の部分はコンピュータのユーザー名に置き換えてください）。

C:\Users\YourName\AppData\LocalLow\VRChat\VRChat

このフォルダの中にはさらにいくつかのフォルダと、以下のような名前のファイルがいくつか存在します。

output_log_08-55-48.txt

これらがログファイルです。VRChatを起動するたびに新しいファイルがタイムスタンプ付きで作成され、個別に管理されます。テキストエディタでこれらのファイルを開くと、セッション中に何が起きたのかという詳細な情報を確認できます。

Udonデバッグの有効化方法

デフォルトでは、VRChatのログにはUdonに関する詳細情報は含まれていません。

VRChat Control Panelのボタンを使用してワールドを「Build and Test」する場合、Unityは追加のデバッグ機能を有効にした状態でVRChatを起動します。これにより、可能な限りのすべての情報を得ることができます。

Build and TestがVRChatを起動する際の方法を再現するには、追加の起動パラメータを指定してVRChatを起動する必要があります。

VRChatの起動パラメータを設定するには、以下に説明する3つの方法があります。

1. VRC Quick Launcher

VRC Quick Launcherを使用すると、有効にするデバッグ機能を選択できます。VRC Quick Launcherは、Creator Companionの「Tools」タブから見つけることができます。

2. バッチファイル

バッチファイルを使用して、特殊なオプション付きでVRChatを起動できます。バッチファイルとは、特殊なコマンドが含まれたプレーンテキストファイルのことです。これを使用すると、デバッグを有効にした状態でVRChatをすぐに開始できる便利なショートカットを作成できます。

お使いのPCの VRChat.exe と同じ場所に、 debug.bat という名前の新しいテキストファイルを作成します。
そのファイルに次の行を追加します： VRChat.exe --no-vr --enable-debug-gui --enable-sdk-log-levels --enable-udon-debug-logging
- このコマンドは、詳細ログ用の3つのフラグをオンにし、さらにデスクトップテスト用にVRChatのVRモードを強制的にバイパスします。
- 他にも指定できるオプションがあります。 VRChat Launch Options ページにあるフラグだけでなく、 Unity Standalone Player command line arguments も含めることが可能です。
- 例として、次のコマンドは2つ目のVRChatプロファイルでVRChatを起動し、画面の高さを720ピクセルに強制設定します：

VRChat.exe --profile=1 --no-vr --enable-debug-gui --enable-sdk-log-levels --enable-udon-debug-logging -screen-width 1280 -screen-height 720

バッチファイルを保存して実行します。
（任意）バッチファイルを右クリックしてショートカットを作成し、そのショートカットをデスクトップに移動します。
バッチファイルをダブルクリックして実行します。

3. Steamの起動オプション

Steam版のVRChatを使用している場合は、VRChatの起動オプションを変更することでデバッグを有効にできます。

SteamライブラリでVRChatを右クリックし、「プロパティ」を選択します。
「一般」タブにある「起動オプションを設定」ボタンを押します。
表示されたフィールドに、常に有効にしたいVRChat固有のフラグを入力します。例えば、 --enable-debug-gui --enable-udon-debug-logging と入力すると、Debug GUIとUdonデバッグが常に有効になります。

デバッグによるパフォーマンス低下

デバッグを常に有効にしておくことは推奨されません。VRChatのパフォーマンスが低下し、ログファイルのサイズが増大するためです。必要がないときはデバッグを無効にしてください。

Udonプログラムにログを追加する方法

Udonが意図した通りに動作しない場合は、Debug Log ノードを使用して独自のテキストを出力するのが有効な診断方法です。これはスクリプト内のどこででも、いつでも実行可能です。例：

An Udon Graph showing the "InputJump" event, "Debug Log" node, and a string constant.

using UdonSharp;  
using UnityEngine;  
using VRC.Udon.Common;  

public class JumpDetector : UdonSharpBehaviour  
{  
    public override void InputJump(bool value, UdonInputEventArgs args)  
    {  
        Debug.Log("Local player jumped!");  
    }  
}

スクリプトの重要な処理の前後でログメッセージを追加しましょう。UdonBehaviourが実行されたら、UnityまたはVRChatのログを確認して、メッセージが出力されているかチェックしてください。これにより、スクリプトが期待通りに動作しているか、あるいは Debug.Log が実行される前に停止してしまっていないかを確認できます。

Udon エラーの理解

UdonBehaviour がクライアント実行中に重大な問題に遭遇すると、その動作は停止（無効化）されます。VRChat のログを確認すると、以下のようなエントリが表示されます：

[UdonBehaviour] An exception occurred during Udon execution, this UdonBehaviour will be halted.

何が起きたのかを詳しく調べるには、前述の ログの場所 (Finding Your Logs) の手順に従ってログファイルを開き、「halted」という単語を検索してください。そこに、発生した問題に関する詳細情報が記載されています。

例

Udon で遭遇する可能性のあるエラーの例を見てみましょう。分解して解説します。

2020.08.28 17:40:51 Error      -  [UdonBehaviour] An exception occurred during Udon execution, this UdonBehaviour will be halted.
VRC.Udon.VM.UdonVMException: An exception occurred in an UdonVM, execution will be halted. ---> VRC.Udon.VM.UdonVMException: An exception occurred during EXTERN to 'VRCSDK3VideoComponentsBaseBaseVRCVideoPlayer.__GetTime__SystemSingle'. ---> System.NullReferenceException: Object reference not set to an instance of an object.
  at VRC.SDK3.Internal.Video.Components.AVPro.AVProVideoPlayerInternal.GetTime () [0x00000] in <00000000000000000000000000000000>:0 
  at VRC.Udon.Wrapper.Modules.ExternVRCSDK3VideoComponentsBaseBaseVRCVideoPlayer.__GetTime__SystemSingle (VRC.Udon.Common.Interfaces.IUdonHeap heap, System.UInt32[] parameterAddresses) [0x00000] in <00000000000000000000000000000000>:0

重要な情報は2行目にあります。
- An exception occurred during EXTERN to 'VRCSDK3VideoComponentsBaseBaseVRCVideoPlayer.__GetTime__SystemSingle'. ---> System.NullReferenceException: Object reference not set to an instance of an object.
このエラーは、ワールドが「存在しない何か」にアクセスしようとしていることを伝えています。
- 具体的には、スクリプトが VRCVideoPlayer を割り当てていない状態で、それにアクセスしようとしました。それが Object reference not set to an instance of an object という意味であり、VRCSDK3VideoComponentsBaseBaseVRCVideoPlayer.__GetTime__SystemSingle は、VRCVideoPlayer に対して GetTime を呼び出そうとした際に発生したことを示しています。
- ログの読み方に慣れると、こうした情報は非常に価値のあるものとなります。
これで、VRCVideoPlayer.GetTime を呼び出そうとしているグラフに移動し、そこに VRCVideoPlayer が正しく接続されているかを確認できるようになります。

Debug Log を使用した Udon の診断

Udon が意図した通りに動作しない場合は、ログを追加して診断するのが効果的です。

Udon Graph に Debug Log ノードを追加するか、UdonSharp で Debug.Log を実行してください。「The Rotating Cube script has finished running its Start event.」のように、ログの内容を理解しやすい固有のメッセージを追加しましょう。

スクリプト内の重要な処理の直前または直後に Debug Log を配置します。UdonBehaviour を実行すると、ログを確認することで、処理がどこまで進んでいるか、また期待通りに動作しているかを把握できます。

UnityでUdonSharpのログを確認する

UdonSharpには、VRChatの出力ログからUdonの例外を監視するランタイム例外ウォッチャーが組み込まれています。これにより、UdonSharpスクリプトのどの行で例外が発生したかを正確に特定できます。この機能はデフォルトで有効になっていますが、Project Settingsから無効にすることも可能です。

Project Settings Listen for Client Exceptions

VRChat内でワールドの実行中に発生したエラーは、エディタのConsoleに表示されます。例えば、以下の例ではスクリプト FullBodyPlayerTracker.cs の92行目、86文字目でエラーが発生しています。

Error in Console

標準的な英語US QWERTY配列のキーボードでは、「Backtick」は左上、1キーの隣にあります。チルダ（~）の記号と同じキーです。 ↩

最終更新: 2025年4月10日