跳转到内容

12. UdonSharp 的支持范围与使用条件

约 55 分钟 内容:进阶 动手章

UdonSharp 使用 C# 写法,但并不实现某个 C# 语言版本的全部规范。普通 Unity 示例能编译,不代表放进 UdonSharp 后仍能使用同一套 API 和类型。

平台关系章区分了 .NET、Unity 和 Udon。具体脚本问题可以分成四类:

API 是否开放 → 查 Class Exposure Tree
语言特性是否支持 → 查 UdonSharp 文档和当前编译结果
源码、程序和组件的关联 → 查 ProgramAsset 与场景配置
运行条件是否满足 → 查事件、引用、状态和日志

Udon 开放了一部分 Unity、VRChat 和 .NET API。文件系统、任意网络访问、外部进程等能力不能按普通桌面 C# 程序的方式使用。

普通 C# 中的需求Udon 中的处理边界
读取或写入任意本地文件不应把 System.IO 当作世界脚本可用通道
发起任意 HTTP 请求使用 VRChat 支持的受限下载 API,并遵守其 URL 与信任设置
启动外部进程不属于世界脚本可用能力
跨会话保存玩家数据使用官方 Persistence 机制及其容量、加载时序和权限要求
动态列表或字典使用支持的数据容器,而不是直接移植 List<T>

可用的受限外部数据方案包括 VRCUrl 与 VRCStringDownloader;它们不等于完整 System.Net,也不保证任何网址都能下载。具体请求条件见 String Loading。玩家数据方案见 Persistence。

  1. 打开 Unity 菜单 VRChat SDK → Udon Sharp → Class Exposure Tree。
  2. 搜索目标类型,例如 UnityEngine.Light。
  3. 展开具体方法或属性,而不是只检查类型名。
  4. 绿色表示已暴露,红色表示未暴露;查继承成员时使用 Show base members。
  5. 对照当前项目 SDK 版本编译一个最小调用,记录实际错误。

API 是否暴露与语言特性是否支持是两道检查。类存在不表示它的所有方法都可用,using 也不会扩大 Udon 权限。参见 官方 Class Exposure Tree。

官方支持列表包含基础控制流、数组、用户方法与属性、静态用户方法、字符串插值、部分继承和 ref/out 等能力。不能把 static、属性或 ref/out 一律列为禁用。

当前文档明确指出 List<T> 等通用泛型集合不能直接使用,支持数组和 VRChat 数据容器。自定义接口、泛型类型等高级用法不能从「基础语法相同」推断为完整支持。

普通 C# 的 async/await、迭代器协程及异常捕获,不是本书 UdonSharp 示例采用的执行方式。等待动作使用延迟事件;空引用和输入错误在调用前检查。

官方文档的部分历史 FAQ 与主支持列表仍有不同口径。遇到冲突时,记录所用 SDK 版本,核对主支持列表与编译器诊断,不依赖无版本的旧教程。参见 UdonSharp 支持范围。

逐项写法与替代见 API 清单、语言特性清单和 替代写法对照。

需要「一次交互后等待一秒执行」时,可以注册延迟自定义事件:

DelayedMessage.cs
using UdonSharp;
using UnityEngine;
public class DelayedMessage : UdonSharpBehaviour
{
private bool waiting;
public override void Interact()
{
if (waiting) return;
waiting = true;
Debug.Log("已登记延迟事件");
SendCustomEventDelayedSeconds(nameof(OnTimerFinished), 1f);
}
public void OnTimerFinished()
{
waiting = false;
Debug.Log("延迟事件执行");
}
}

将脚本挂到带 Collider 的可交互物体。交互后应先出现第一条日志,约一秒后出现第二条;等待期间再次交互不会重复登记,这是 waiting 判断的结果。

SendCustomEventDelayedSeconds 登记的是另一次方法调用,不会暂停当前方法。目标方法需要是可被自定义事件调用的 public 方法。时间取决于事件调度与帧更新,不应拿它作高精度计时保证。

如果删除 waiting 限制,连续操作就可能排入多次回调。该方法也不等于一套可暂停、取消并恢复完整执行状态的协程。参见 官方延迟事件说明。

UdonSharp 不支持用普通 try / catch / finally 捕获运行异常,编译器对此有明确诊断。空引用访问可能使 Udon Behaviour 停止执行,因此检查应发生在访问之前,而不是依赖下一次事件自行恢复。参见 官方编译器实现。

下面是普通 C# 的异常处理对照,不能放进本例的 UdonSharp 脚本:

// 普通 C# 对照;UdonSharp 不支持 try/catch
try
{
target.SetActive(false);
}
catch (System.NullReferenceException)
{
Debug.Log("Target 引用为空");
}

UdonSharp 的替代是先判断再调用:

SafeHide.cs
using UdonSharp;
using UnityEngine;
public class SafeHide : UdonSharpBehaviour
{
[SerializeField] private GameObject target;
public override void Interact()
{
if (target == null)
{
Debug.LogWarning("SafeHide:Target 未配置或对象已不存在");
return;
}
target.SetActive(false);
}
}

创建 U# Script SafeHide 并挂到带 Collider 的独立按钮,把另一个可见 Cube 拖入 Target;按钮不能是被禁用的目标或它的子物体。提示设为 隐藏目标 / Hide target。在 ClientSim 中交互,检查两种输入:配置有效目标时,该对象被禁用;在测试副本中清空字段时,出现警告,事件结束。判空只处理对象引用无效,数组越界、类型不匹配等问题仍需要对应检查。

用合适的数据结构保存多项数据

Section titled “用合适的数据结构保存多项数据”

普通 C# 可定义 class Enemy { public string name; public int hp; },再调用 new Enemy() 保存一组数据。这与 new MonoBehaviour() 是两个不同问题:前者是纯数据对象,后者涉及 Unity 组件。不能把普通数据类实例化也视为当前 UdonSharp 已支持的通用工作流;本例使用数组明确保存对应的数据。

新建 U# Script ItemTable:

ItemTable.cs
using UdonSharp;
using UnityEngine;
public class ItemTable : UdonSharpBehaviour
{
[SerializeField] private string[] itemNames;
[SerializeField] private int[] itemScores;
[SerializeField] private int selectedIndex;
public override void Interact()
{
PrintItem(selectedIndex);
}
private void PrintItem(int index)
{
if (itemNames == null || itemScores == null) return;
if (index < 0 || index >= itemNames.Length || index >= itemScores.Length)
{
Debug.LogWarning("ItemTable:索引超出已配置的数组");
return;
}
Debug.Log(itemNames[index] + ": " + itemScores[index]);
}
}

把脚本挂到带 Collider 的测试 Cube,Interaction Text 填 输出条目 / Print item。在 Inspector 将 Item Names 和 Item Scores 的 Size 都设为 2,分别填入 钥匙、徽章 与 10、20;Selected Index 设为 0。ClientSim 交互应输出「钥匙: 10」。退出 Play Mode,改为 1 再测试,应输出「徽章: 20」;在副本中改为 2,应输出越界警告。

两组数组的同一索引表示同一条目,长度与顺序需一起维护。边界检查只能阻止越界,不能发现「钥匙错误对应 20 分」这样的配置错误。Build & Test 的输出在对应客户端日志中查看。

如果每组数据本来就对应一个场景对象,可以把字段写在 UdonSharpBehaviour 上,通过 Inspector 引用这些行为。这样对象配置有明确位置,但也会增加组件与跨行为调用,需要按需求选择。

不能直接把普通 C# 中 new 一个 MonoBehaviour 的思路当成创建场景组件;组件的生命周期和场景关联由 Unity/SDK 管理。

动态容器:DataList 与 DataDictionary

Section titled “动态容器:DataList 与 DataDictionary”

VRChat 提供 VRC.SDK3.Data 命名空间中的动态容器。以下完整例子在 Start 创建列表并输出第一个整数:

ScoreListExample.cs
using UdonSharp;
using UnityEngine;
using VRC.SDK3.Data;
public class ScoreListExample : UdonSharpBehaviour
{
private DataList scores;
private void Start()
{
scores = new DataList();
scores.Add(10);
scores.Add(20);
DataToken first;
if (scores.TryGetValue(0, TokenType.Int, out first))
{
Debug.Log("第一项 = " + first.Int);
}
}
}

将 ScoreListExample 挂到一个启用的空 GameObject,进入 ClientSim 后查 Unity Console,应在启动时输出「第一项 = 10」。不需要 Collider,也不需要手动点击。

容器元素使用 DataToken 表示,读取时要确认索引与类型。.Int 适用于整数 token,不能不检查地用于任意元素。容器的存在也不会自动提供网络同步或持久化;这些是另外的配置。参见 官方数据容器。

创建 U# 脚本时,工具会产生 .cs 和配套程序资产。普通 C# 辅助文件、Unity 编辑器工具与 Udon 程序资产不是同一种文件。

如果出现下面的错误:

Script without UdonSharpBehaviour definition should not have an associated UdonSharpProgramAsset

应检查程序资产关联的源码是否确实定义了预期行为:

  1. 选中报错涉及的 UdonSharpProgramAsset,检查它引用的 .cs。
  2. 核对该文件是否声明了正确的 UdonSharpBehaviour 类,类名和文件名是否一致。
  3. 检查是否把纯辅助文件误关联为一个行为程序。
  4. 检查场景组件是否仍引用原有程序资产,避免替换正在被使用的关联。
  5. 修正后重新编译,并验证场景中的序列化字段。

Plugins 目录不会自动把任意 C# 库变成 Udon 可执行代码,移动文件也不能代替修正错误的资产关联。跨文件组织应遵循当前 UdonSharp 与 Unity 程序集规则。

如果多个脚本需要相同的固定数值,可以把 const 放在一个辅助文件,使用类名访问。下面的数值只是样例配置,不设置世界人数上限或玩家的实际移动速度。

在 Assets/Scripts/WorldConstants.cs 创建普通 C# 文件,文件内容替换为:

WorldConstants.cs
public static class WorldConstants
{
public const float DefaultWalkSpeed = 2f;
public const int MaxPlayers = 32;
}

此文件不继承 UdonSharpBehaviour,不挂到场景,也不通过 Create → U# Script 给它创建程序资产。示例两个文件放在同一个默认程序集下,不引入自定义 asmdef 或 Plugins 目录。

另用 Create → U# Script 创建实际运行的读取者:

ConstantsProbe.cs
using UdonSharp;
using UnityEngine;
public class ConstantsProbe : UdonSharpBehaviour
{
private void Start()
{
Debug.Log("样例速度 = " + WorldConstants.DefaultWalkSpeed);
Debug.Log("样例容量 = " + WorldConstants.MaxPlayers);
}
}

把 ConstantsProbe 挂到启用的空 GameObject。保存并检查编译错误,再进入 ClientSim 查 Console,预期两项为 2 和 32。把 WorldConstants.MaxPlayers 改为 16,重新编译并重新进入 Play Mode,应读到 16;其他脚本也可用同一类名访问,不必各留一份数字。常量不在 Inspector 调整,也不会在运行时向其他客户端广播变化;修改后要重新编译和构建。

此例的依据是 Worlds SDK 3.10.5 官方包中 BoundFieldAccessExpression.BindFieldAccess 对 const 字段生成常量表达式的处理,以及 FieldSymbol 对 const 与可变 static 字段的区分。本轮完成的是源码核对,未执行 Unity/Udon 编译;上述步骤是项目内的验证入口,不是已通过测试的记录。它不证明任意静态状态或任意外部库可用。

官方支持列表包含静态用户方法。下面的完整例子只计算两个整数的和,不使用实例字段:

StaticMathProbe.cs
using UdonSharp;
using UnityEngine;
public class StaticMathProbe : UdonSharpBehaviour
{
private void Start()
{
Debug.Log(Add(3, 5));
}
private static int Add(int a, int b)
{
return a + b;
}
}

创建对应 U# Script,挂到启用的空物体,在 ClientSim 启动时检查 Console 是否输出 8。

支持静态方法不代表可任意使用静态状态、外部 .NET 库或未开放 API。遇到相关错误时,应检查具体方法体与当前编译器支持,而不是把所有代码改放到某个目录。

要让一个带行为的物体按需出现,可以在编辑阶段配置对象与程序,然后切换它的激活状态;也可以使用受支持的实例化或对象池方案。

不能把 gameObject.AddComponent<MyBehaviour>() 当作运行时添加任意 UdonSharpBehaviour 的通用方式。Udon 程序、组件和序列化数据需要正确关联,普通 Unity 的动态组件示例不能直接照搬。

对预放置物体使用 SetActive(true) 前,确认它不是承载唯一控制器的对象;禁用控制器自身可能使恢复操作失去事件入口。

// 字段初始值用于默认配置
[SerializeField] private float speed = 2f;
private Transform cachedTransform;
// 场景相关引用在行为开始运行时取得
private void Start()
{
cachedTransform = transform;
}
// Unity 生命周期方法不使用 override
private void Update()
{
// 每次调用只处理当前帧需要的有限工作
}
// UdonSharp 交互事件使用对应的基类签名
public override void Interact()
{
Debug.Log("收到交互");
}

这是同一类内部的片段,不能作为独立文件直接编译。字段初始化器与 Inspector 序列化值还需区分:改了源码默认值,不保证覆盖已保存实例上的旧值。

依赖其他场景对象的初始化放在 Start 等适当事件中。不同对象之间的启动顺序不能凭 Hierarchy 排列推断;如果初始化依赖外部数据到达,应检查对应完成条件。

持有其他 UdonSharpBehaviour 的引用后,可以调用受支持的方法,也可以使用 SendCustomEvent。自定义事件需要 public 入口;仅供本类使用的方法可设为 private。

例如按钮调用另一个物体上的灯光控制器。分别创建两个 U# Script:

LightReceiver.cs
using UdonSharp;
using UnityEngine;
public class LightReceiver : UdonSharpBehaviour
{
public Light targetLight;
public void ToggleLamp()
{
if (targetLight != null) targetLight.enabled = !targetLight.enabled;
}
}
RelayButton.cs
using UdonSharp;
using UnityEngine;
public class RelayButton : UdonSharpBehaviour
{
public LightReceiver receiver;
public override void Interact()
{
if (receiver == null) return;
receiver.SendCustomEvent(nameof(LightReceiver.ToggleLamp));
}
}

LightReceiver 挂到启用的空物体,Target Light 引用一盏实时灯;RelayButton 挂到带 Collider 的按钮,Receiver 拖入前一个物体上的 LightReceiver 组件。设置交互提示后在 ClientSim 或 Build & Test 连续点击两次,灯应切换并恢复。在测试副本中清空 Receiver,按钮不应改变灯。这里发送的是本机自定义事件,不是网络事件。

有具体类型引用时,也可把调用一行替换为 receiver.ToggleLamp();。这两个版本二选一,不要同时调用,否则同一次点击切换两次后会回到原状态。更多签名对照见 附录的跨脚本与生命周期说明。

Udon 的执行开销依赖代码和调用方式,不能按普通 Unity C# 的耗时直接估算。可检查:

  • 是否每帧遍历了本可在事件发生时处理的数据
  • 是否重复查找同一个组件,而没有缓存引用
  • 是否把同一项工作拆成大量跨 Behaviour 调用
  • 是否已有组件或动画能够直接完成需求
  • 是否在目标客户端测过耗时,而不只是在编辑器看结果

执行链中的开销量级说明 200–1000 倍的适用边界,性能清单说明 UdonSharpBehaviour 类型匹配和 public 事件查找成本。

这些是减少不必要工作的方向,不是禁止使用 Update、循环或 public 方法。具体成本见 官方性能建议。

  1. 编译:保存脚本,查看第一条相关错误及完整信息;确认新程序确实生成。
  2. 关联:检查组件、程序资产与 .cs 是否对应。
  3. 配置:检查引用槽、数组长度、参数和对象激活状态。
  4. 事件:在入口加一条日志,复现同一操作,判断有没有进入。
  5. 执行:记录状态变化前后的值,定位中断或结果不符的语句。
  6. 环境:区分 Unity ClientSim 与实际客户端,检查平台和网络条件。

ClientSim 已包含在 Worlds SDK 中;按本书的 VCC 项目配置不需要另从 GitHub 手动导入。打开世界场景,按 Unity 的 Play,在 Game 窗口操作,在 Console 查看编辑器日志。ClientSim 通过 Unity Play Mode 模拟一部分 VRChat 世界行为,可以检查交互、变量和日志,但不覆盖完整客户端及多人同步条件。网络、设备和实际性能问题需要相应客户端测试。参见 ClientSim 官方说明。