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

デバッグとは、VRChatや自分のワールド、そしてUdonコードの裏側で何が起きているかを把握するための手段です。これはプログラミング全般において、そしてワールドを構築する上で身につけておくべき重要なスキルです。

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

VRChatのDebug log

エラーを見つけやすくし、その内容を理解しやすくするために、VRChatは訪問したワールドや発生したエラー、その他のバックグラウンド情報を記録します。これらは「output log」や「debug log」と呼ばれます。

VRChatのログには、VRChat内から直接アクセスするか、PC上のテキストファイルとしてアクセスできます。

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

Debug GUIを有効にしてVRChatを起動すると（下記参照）、デスクトップモードとVRモードの両方で特別なDebugオーバーレイをオンにすることができます。発生したdebug logメッセージを確認するには、RShift + Backtick¹ + 3 を押してください。利用可能な各種Debugオーバーレイのショートカットについては、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に記載されているフラグを自由に追加できます。
- 例として、以下のコマンドは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 Launch Options

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

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

デバッグを行うとパフォーマンスが低下します

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

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

Udonが期待通りに動作しない状況に陥った場合、その診断には固有のテキストを設定したDebug logノードを追加するのが効果的です。これはスクリプト内のどこにでも、いつでも追加できます。例として以下をご覧ください：

Udon Graph
UdonSharp

「InputJump」イベント、Debug logノード、および文字列定数を示すUdon Graph

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の実行中に重大な問題が発生すると、その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 内で発生したエラーは、エディターのコンソールに表示されます。例えば以下の例では、スクリプト FullBodyPlayerTracker.cs の92行目、86文字目の位置でエラーが発生しています：

コンソール内のエラー

標準的な英語配列（US QWERTY）キーボードにおいて、「バッククォート」は左上、1キーの隣にあるキーです。このキーにはチルダ（~）も割り当てられています。↩

最終更新: 2025年4月4日