附录 D · UdonSharp 限制
UdonSharp 的兼容性问题可分别检查三个层面:
- 白名单层:沙箱不让 Udon 调那个 API。表现是编译时报「unexposed member」或运行时干脆不动。原因见第 12 章 · API 开放范围。
- 编译器层:UdonSharp 编译器自身还没把那条 C# 特性翻译过来。表现是编译报错。
- 工程化层:语法不报错也能跑,但脚本布局或运行时调用方式不符合 UdonSharp 的工作流。
本附录按 API 暴露、语言特性和项目组织分类,提供替代写法与正文回链。
主源是第 12 章 · UdonSharp 的支持范围与使用条件。术语层细节见附录 A · UdonSharp 限制与替代写法。
D.1 白名单层(沙箱拦的)
Section titled “D.1 白名单层(沙箱拦的)”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 暴露限制与编译器语法支持是两项独立条件。不能只凭功能看似安全就判断可用,也不能把某类语法限制全部归因于安全策略。
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 跑一次编译器即知 |
D.3 工程化层(脚本布局、生命周期、运行时行为)
Section titled “D.3 工程化层(脚本布局、生命周期、运行时行为)”程序还需与场景组件、程序资产和生命周期正确关联。
| 情况 | 表现 | 修法 |
|---|---|---|
| 程序资产关联到不符合预期的脚本类型 | 可能报「Script without UdonSharpBehaviour definition should not have an associated UdonSharpProgramAsset」 | 检查程序资产关联、继承类型和程序集设置;移入 Plugins 不会解锁不支持的语法 |
| 静态方法直接访问实例字段 | 没有实例引用时无法访问对应对象状态 | 传入所需参数,或把逻辑放到有场景引用的实例方法 |
共享固定数值的完整文件、程序集条件与验证入口见 WorldConstants 与 ConstantsProbe。该例读取 const,不代表支持任意可变 static 字段。
运行时行为差异
Section titled “运行时行为差异”| 普通 Unity / C# 的写法 | 在 UdonSharp 里 | 替代 |
|---|---|---|
gameObject.AddComponent<MyBehaviour>() 运行时挂脚本 | 走不通:UdonSharp 脚本要在编辑期就跟 GameObject 绑好 | 场景里预放好挂脚本的物体、禁用着,按需 SetActive(true) |
跨脚本直接 otherScript.Method() | 取决于脚本引用方式:拿到具体子类引用可以直接调;只有基类引用要走 SendCustomEvent | 有具体类型引用时可直接调用;按名称触发公开无参数事件时用 SendCustomEvent |
private 方法被 SendCustomEvent("M") 调用 | 调不到——SendCustomEvent 只认 public 方法 | 真正要外部调的设 public;只本脚本用的设 private(也能少一点查找开销) |
| 字段名写错了会运行时找不到 | 字符串名字写错了运行时才会报错 | 用 nameof(MethodName) 代替手写字符串,改名时编译器立刻提示 |
生命周期方法签名
Section titled “生命周期方法签名”事件签名分两类:
// Unity 标准生命周期方法(Start / Update / FixedUpdate / LateUpdate / OnEnable / OnDisable)// 不写 overrideprivate void Start() { ... }private void Update() { ... }
// VRChat / UdonSharp 提供的事件(Interact / OnPickup / OnPlayerJoined / OnStationEntered / 等)// 必须写 public overridepublic 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() 里反复 GetComponent | Start() 里缓存组件引用到字段 |
每帧跨 UdonBehaviour 调 SendCustomEvent | 把跨脚本调用挪到事件发生时,而不是每帧 |
把一堆方法都写成 public | 真正要给外部调的才 public;只本脚本用的 private |
| 用脚本做能用动画 / Collider / 现成组件解决的事 | 优先用动画 / Collider / 现成组件 |
查找 UdonSharpBehaviour 时还涉及脚本类型匹配。能在 Inspector 配好的引用可直接序列化,动态查找则在需要时执行并缓存;不要把所有 GetComponent 都描述成反射。
D.5 替代写法对照
Section titled “D.5 替代写法对照”下表对照普通 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)) |
| 按名字调别人脚本上的方法 | 反射 / delegate | other.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.SetInt | Player Persistence API(SDK 3.7.4+) |
D.6 排查顺序
Section titled “D.6 排查顺序”第 12 章末尾给了一份具体的排查顺序,移到这里方便回查:
- 看 Console 里有没有红字。先处理导致编译失败的错误,再复查派生错误。
- 看脚本是否真的挂在了想让它执行的 GameObject 上。
- 看 Inspector 里每个引用槽是否真指向了目标物体。引用为 None 时访问其成员可引发 NullReferenceException,并可能使该 UdonBehaviour 停止执行。
- 看用到的 API 是否在白名单上(
Class Exposure Tree,或让编译器告诉你)。对应 D.1。 - 看是否撞上 UdonSharp 编译器的特性限制(
async/yield/ 泛型 /interface/try-catch等)。对应 D.2。 - 看是否撞上工程化约束(程序资产关联不符、运行时 AddComponent、SendCustomEvent 目标不是公开方法…)。对应 D.3。
- 都不是,加
Debug.Log把变量值打出来。
日志定位方法见第 40 章。
- 第 12 章 · UdonSharp 的支持范围与使用条件 — 主源
- 第 11 章 · 刚好够用的 C# — 基础语法(哪些是标准 C#)
- 第 40 章 · 调试心态 — Console、
Debug.Log、NRE排查 - 附录 A · UdonSharp 限制与替代写法 — 词条层细节
外部参考: