跳转到内容

附录 D · UdonSharp 限制

约 7 分钟

UdonSharp 的兼容性问题可分别检查三个层面:

  1. 白名单层:沙箱不让 Udon 调那个 API。表现是编译时报「unexposed member」或运行时干脆不动。原因见第 12 章 · API 开放范围。
  2. 编译器层:UdonSharp 编译器自身还没把那条 C# 特性翻译过来。表现是编译报错。
  3. 工程化层:语法不报错也能跑,但脚本布局或运行时调用方式不符合 UdonSharp 的工作流。

本附录按 API 暴露、语言特性和项目组织分类,提供替代写法与正文回链。

主源是第 12 章 · UdonSharp 的支持范围与使用条件。术语层细节见附录 A · UdonSharp 限制与替代写法。


VRChat 沙箱让 Udon 只能调用一份白名单内的 .NET / Unity API。判断某个 API 在不在白名单:VRChat SDK → Udon Sharp → Class Exposure Tree,或者直接写一行让编译器告诉你。

普通 C# / Unity 里的写法在 UdonSharp 里替代
System.IO.File.ReadAllText(path)调不到,未向 Udon 暴露想存玩家数据走 Player Persistence API(SDK 3.7.4+);想从外部读文本走 VRCUrl + VRCStringDownloader
System.Net.Http.HttpClient / WebRequest调不到VRCUrl + VRCStringDownloader;只能直接下载官方信任列表里的域名,其他地址需要玩家在设置里允许不受信任 URL
System.Reflection.*(反射)调不到反射 API 不属于 Udon 的通用可调用能力。按名称调用公开自定义事件可用 SendCustomEvent("方法名")
System.Diagnostics.Process.Start(...)调不到没有等价物,世界不能启动外部程序
System.Threading.* / Task / async / await调不到想”过 N 秒做某事”用 SendCustomEventDelayedSeconds(nameof(M), N)
System.Linq(.Where / .Select / .OrderBy)调不到写循环 + 临时数组;动态长度场景用 DataList
List<T> / Dictionary<TKey, TValue>(泛型集合)当前 UdonSharp 不当作可用能力数组 T[] 够用就用;不够用上 DataList / DataDictionary(命名空间 VRC.SDK3.Data)

API 暴露限制与编译器语法支持是两项独立条件。不能只凭功能看似安全就判断可用,也不能把某类语法限制全部归因于安全策略。

回链:第 12 章 · API 开放范围。


D.2 编译器层(UdonSharp 还没支持的 C# 特性)

Section titled “D.2 编译器层(UdonSharp 还没支持的 C# 特性)”

以下按 UdonSharp 的语法支持范围检查;具体错误应结合所用 SDK 版本与编译信息确认。

C# 特性在 UdonSharp 里替代
async / await不支持SendCustomEventDelayedSeconds(nameof(M), seconds)
yield return / IEnumerator / 协程不支持同上
自定义泛型类 class Foo<T> 与非静态泛型方法不支持按具体类型各写一份;或绕到 DataList + DataToken
自定义 interface 实现不作为本书可用方案按具体 UdonSharpBehaviour 引用组织行为
try / catch / finally不支持先判后用:if (target != null) { ... },参考第 12 章 · 调用前检查引用
event 关键字不支持用 SendCustomEvent / SendCustomNetworkEvent 模拟广播
自定义 indexer this[int i]不支持公开一个数组字段,外部用 obj.array[i] 直接读
自定义 operator overload(== / + / -)不支持写命名方法 static Vec2 Add(Vec2 a, Vec2 b) 代替
static 工具方法当前 UdonSharp 文档列为支持可以用于纯计算;涉及场景对象、Inspector 引用或生命周期的逻辑仍放回实例方法
new 一个自定义数据类(如 new Enemy())官方不当作支持的工作流三选一:并行数组 / 挂在 GameObject 上的 UdonSharpBehaviour 字段 / DataList + DataDictionary;见第 12 章 · 用合适的数据结构保存多项数据
ref / out 参数官方列明支持,包括自定义方法与部分外部 API按具体 API 签名传入相应类型的变量
C# 8 switch 表达式 e switch { ... }受限用传统 switch 语句 switch (e) { case ...: }
字符串内插 $"score = {score}"当前版本可用老社区帖子可能写”不能用”,按当前 SDK 跑一次编译器即知

回链:第 12 章 · 语言特性需要逐项核对。


D.3 工程化层(脚本布局、生命周期、运行时行为)

Section titled “D.3 工程化层(脚本布局、生命周期、运行时行为)”

程序还需与场景组件、程序资产和生命周期正确关联。

情况表现修法
程序资产关联到不符合预期的脚本类型可能报「Script without UdonSharpBehaviour definition should not have an associated UdonSharpProgramAsset」检查程序资产关联、继承类型和程序集设置;移入 Plugins 不会解锁不支持的语法
静态方法直接访问实例字段没有实例引用时无法访问对应对象状态传入所需参数,或把逻辑放到有场景引用的实例方法

回链:第 12 章 · 源码与程序资产的关联。

共享固定数值的完整文件、程序集条件与验证入口见 WorldConstants 与 ConstantsProbe。该例读取 const,不代表支持任意可变 static 字段。

普通 Unity / C# 的写法在 UdonSharp 里替代
gameObject.AddComponent<MyBehaviour>() 运行时挂脚本走不通:UdonSharp 脚本要在编辑期就跟 GameObject 绑好场景里预放好挂脚本的物体、禁用着,按需 SetActive(true)
跨脚本直接 otherScript.Method()取决于脚本引用方式:拿到具体子类引用可以直接调;只有基类引用要走 SendCustomEvent有具体类型引用时可直接调用;按名称触发公开无参数事件时用 SendCustomEvent
private 方法被 SendCustomEvent("M") 调用调不到——SendCustomEvent 只认 public 方法真正要外部调的设 public;只本脚本用的设 private(也能少一点查找开销)
字段名写错了会运行时找不到字符串名字写错了运行时才会报错用 nameof(MethodName) 代替手写字符串,改名时编译器立刻提示

事件签名分两类:

// Unity 标准生命周期方法(Start / Update / FixedUpdate / LateUpdate / OnEnable / OnDisable)
// 不写 override
private void Start() { ... }
private void Update() { ... }
// VRChat / UdonSharp 提供的事件(Interact / OnPickup / OnPlayerJoined / OnStationEntered / 等)
// 必须写 public override
public override void Interact() { ... }
public override void OnPlayerJoined(VRCPlayerApi player) { ... }

签名区别:Unity 自己的生命周期方法不写 override,VRChat 专属事件写 public override。

回链:初始化与事件签名;跨物体调用的两个完整脚本、引用槽和测试见 LightReceiver 与 RelayButton。


D.4 性能层(量级与高成本写法)

Section titled “D.4 性能层(量级与高成本写法)”

Udon 执行与跨 Behaviour 调用有额外开销,不能把任意普通 C# 的性能假设直接套用。按目标客户端测量循环、查找与事件调用成本。200–1000 倍的官方条件性量级与适用范围见 运行开销过高。

不要可以
在 Update() 里遍历很多物体缓存到字段、低频事件里更新
在 Update() 里反复 GetComponentStart() 里缓存组件引用到字段
每帧跨 UdonBehaviour 调 SendCustomEvent把跨脚本调用挪到事件发生时,而不是每帧
把一堆方法都写成 public真正要给外部调的才 public;只本脚本用的 private
用脚本做能用动画 / Collider / 现成组件解决的事优先用动画 / Collider / 现成组件

查找 UdonSharpBehaviour 时还涉及脚本类型匹配。能在 Inspector 配好的引用可直接序列化,动态查找则在需要时执行并缓存;不要把所有 GetComponent 都描述成反射。

回链:第 12 章 · 跨脚本调用与性能。


下表对照普通 C# / Unity 写法与 UdonSharp 方案。

想做的事普通 C# / Unity 写法UdonSharp 替代
过 N 秒做一件事Coroutine + yield return new WaitForSeconds(N) 或 await Task.Delay(N * 1000)SendCustomEventDelayedSeconds(nameof(M), N)
出错时兜住try { ... } catch (NullReferenceException) { ... }if (target != null) { target.X(); }
动态长度的列表List<T>T[](先够用就先用);DataList
键值映射Dictionary<TKey, TValue>DataDictionary
一组数据对象class Enemy { string name; int hp; } + new Enemy()并行数组(string[] names; int[] hps;),或一个挂场景里的 UdonSharpBehaviour 字段,或 DataList + DataToken
按名字调本脚本上的方法Invoke("M", 0f) 或反射SendCustomEvent(nameof(M))
按名字调别人脚本上的方法反射 / delegateother.SendCustomEvent(nameof(Other.M))
按名字调网络上某玩家脚本上的方法—other.SendCustomNetworkEvent(NetworkEventTarget.Owner, nameof(Other.M))
多线程 / 后台任务Task.Run / async / await没有等价物。把工作分摊到多帧(每帧处理一小批)
LINQ 查询arr.Where(x => x > 0).Select(x => x.Name).ToArray()写循环:for (int i = 0; i < arr.Length; i++) { if (arr[i] > 0) ... }
启动外部程序、读写本地文件Process.Start / File.WriteAllText不能
从外部 URL 读文本HttpClient.GetStringAsync(url)VRCStringDownloader.LoadUrl(url, this);url 在编辑期配置或由 VRCUrlInputField 获取,不能运行时用字符串任意构造
持久化玩家数据PlayerPrefs.SetIntPlayer Persistence API(SDK 3.7.4+)

第 12 章末尾给了一份具体的排查顺序,移到这里方便回查:

  1. 看 Console 里有没有红字。先处理导致编译失败的错误,再复查派生错误。
  2. 看脚本是否真的挂在了想让它执行的 GameObject 上。
  3. 看 Inspector 里每个引用槽是否真指向了目标物体。引用为 None 时访问其成员可引发 NullReferenceException,并可能使该 UdonBehaviour 停止执行。
  4. 看用到的 API 是否在白名单上(Class Exposure Tree,或让编译器告诉你)。对应 D.1。
  5. 看是否撞上 UdonSharp 编译器的特性限制(async / yield / 泛型 / interface / try-catch 等)。对应 D.2。
  6. 看是否撞上工程化约束(程序资产关联不符、运行时 AddComponent、SendCustomEvent 目标不是公开方法…)。对应 D.3。
  7. 都不是,加 Debug.Log 把变量值打出来。

日志定位方法见第 40 章。

回链:第 12 章 · 从编译到运行的检查顺序。


外部参考: