调试 Udon 项目

调试是了解 VRChat、您的世界和 Udon 代码内部运行情况的方式。这是编程和构建世界时需要培养的关键技能。

在发布世界之前，在 VRChat 中测试它们非常重要。大多数错误可以在 Unity 编辑器中修复，但有时您会发现在 VRChat 中才能调试的世界或 Udon 程序。

VRChat 的调试日志

为帮助您发现错误并使其更易于理解，VRChat 保存了有关您访问的世界、遇到的错误以及其他幕后信息。这称为"输出日志"或"调试日志"。

您可以直接在 VRChat 中或作为 PC 上的文本文件访问 VRChat 的日志。

1. 在 VRChat 中查看日志

当您在启用调试 GUI 的情况下启动 VRChat（见下文）时，可以在桌面和 VR 模式中打开特殊的调试叠加层。要实时查看日志消息，请按 RShift + 反引号¹ + 3。您可以在键盘和鼠标页面上找到适用于不同调试叠加层的所有快捷键。

2. 在文本编辑器中查看日志

您可以在 VRChat 会话期间或之后，在磁盘上找到这些文件并打开查看。它们通常保存到以下文件夹，请将 'YourName' 替换为您的计算机用户名：

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

在此文件夹中，您会找到更多文件夹和一些名称如下的文件： output_log_08-55-48.txt

这些是您的日志文件——每次启动 VRChat 时都会创建一个新文件，带有时间戳以保持名称唯一。您可以在任何文本浏览器中打开它们，查找会话期间发生的详细信息。

如何启用 Udon 调试

默认情况下，VRChat 的日志不包含 Udon 的详细信息。

当您使用 VRChat 控制面板中的按钮"构建和测试"世界时，Unity 会以启用额外调试功能的方式启动 VRChat。这为您提供所有可能的信息。

要复制构建和测试启动 VRChat 的方式，您需要添加额外的启动参数启动 VRChat。

有三种配置 VRChat 启动参数的方式，如下所述。

1. VRC Quick Launcher

VRC Quick Launcher 允许您选择要启用的调试功能。您可以在 Creator Companion 的"工具"选项卡中找到 VRC Quick Launcher。

2. 批处理文件

您可以使用批处理文件以特殊选项启动 VRChat。批处理文件是包含一些特殊命令的纯文本文件。这为您提供了一个方便的快捷方式，可以立即启动启用了调试的 VRChat。

1. 在您机器上的 VRChat.exe 旁边创建一个名为 debug.bat 的新文本文件。
2. 将以下行添加到文件中：VRChat.exe --no-vr --enable-debug-gui --enable-sdk-log-levels --enable-udon-debug-logging
   • 此命令打开三个标志以进行额外日志记录，并强制 VRChat 绕过 VR 进行桌面测试。
   • 还有更多选项可以传递——您可以包含 VRChat 启动选项页面中的任何标志以及 Unity Standalone Player 命令行参数。
   • 例如，以下命令在您的辅助 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. 保存批处理文件并运行它。
4. （可选）右键单击批处理文件，创建快捷方式，并将快捷方式移动到桌面。
5. 双击运行批处理文件。

3. Steam 启动选项

如果您使用 Steam 版本的 VRChat，可以通过更改 VRChat 的启动选项来启用调试。

1. 在 Steam 库中，右键单击 VRChat 条目并选择"属性"。
2. 在"通用"选项卡中，按"设置启动选项"按钮。
3. 在出现的字段中，您可以输入希望始终启用的 VRChat 特定标志，例如 --enable-debug-gui --enable-udon-debug-logging 以始终启用调试 GUI 和 Udon 调试。

调试会降低性能

不建议始终启用调试。它会降低 VRChat 的性能并增加日志文件的大小。如果不需要，请禁用调试。

如何向 Udon 程序添加日志

如果遇到 Udon 未按预期执行的情况，诊断问题的一个好方法是添加带有唯一文本的 Debug Log 节点。您可以在脚本中的任何位置、任何时间执行此操作。例如：

Udon Graph

UdonSharp

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. 要了解更多信息，请按照上述查找日志中的说明打开日志文件，并搜索"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 

• 重要信息在第二行。
  • An exception occurred during EXTERN to 'VRCSDK3VideoComponentsBaseBaseVRCVideoPlayer.__GetTime__SystemSingle'. ---> System.NullReferenceException: Object reference not set to an instance of an object.
• 此错误告诉您，您正在尝试访问不存在的内容。
  • 具体来说，脚本在未分配 VRCVideoPlayer 的情况下尝试访问它。这就是对象引用未设置为对象实例的含义，而 VRCSDK3VideoComponentsBaseBaseVRCVideoPlayer.__GetTime__SystemSingle 告诉您它在尝试对 VRCVideoPlayer 调用 GetTime 时发生。
  • 一旦您熟悉阅读日志，这类信息将非常宝贵。
• 现在您可以转到尝试调用 VRCVideoPlayer.GetTime 的图表，确保它连接了一个 VRCVideoPlayer。

使用调试日志诊断 Udon

如果遇到 Udon 未按预期执行的情况，诊断问题的一个好方法是添加日志记录。

将 "Debug Log" 节点添加到 Udon Graph，或在 UdonSharp 中执行 Debug.Log。添加独特的消息以帮助您理解日志，例如"旋转立方体脚本已完成 Start 事件的运行。"

在脚本尝试执行重要操作之前或之后放置调试日志。然后运行 UdonBehaviour 时，您可以观察日志以了解执行到什么程度，以及是否按预期运行。

在 Unity 中查看 UdonSharp 日志

UdonSharp 包含一个运行时异常监视器，它会从 VRChat 的输出日志中查找 Udon 异常。它可以让你准确看到 UdonSharp 脚本中抛出异常的代码行。此功能默认启用，但可以在项目设置中禁用：

在 VRChat 中，世界中抛出的任何错误都会显示在编辑器控制台中。例如，在下面的示例中，脚本 FullBodyPlayerTracker.cs 在第 92 行的第 86 个字符处遇到错误：

Footnotes

1. 在标准的美式 QWERTY 布局键盘上，"反引号"是左上角的键，紧挨着 1 键。它与波浪号（~）字符共用一个键。 ↩