Skip to main content

UdonSharp

UdonSharp 允许您使用 C# 创建 Udon 脚本。UdonSharp 包含在 VRChat Worlds SDK 中，并将您的 C# 编译为 Udon Assembly 代码。

  • 添加有用的特性以扩展 UdonSharp 脚本的功能。
  • 打开类暴露树查看 UdonSharp 中可用的 C# 类和方法。
  • 更改配置以禁用自动编译或更改其他设置。
  • 学习如何编写自定义编辑器脚本。
  • 了解如何迁移使用非常旧版本 UdonSharp 的项目。

如何创建 UdonSharp 脚本​

你可以通过项目窗口或层级窗口创建 UdonSharp 脚本，步骤如下。

在项目窗口中​

  1. 在项目资源浏览器中右键单击。
  2. 导航到"Create" > "U# script"。
  3. 点击"U# script"。这将打开一个文件创建对话框。
  4. 为脚本选择一个名称并点击"Save"。
  5. 这将在同一目录下创建一个 .cs 脚本文件和一个为该脚本配置的 UdonSharp 程序资源。

在层级窗口中​

  1. 在场景中创建一个新的游戏对象。
  2. 为对象添加一个 Udon Behaviour 组件。
  3. 在"New Program"按钮下方，点击下拉菜单并选择"Udon C# Program Asset"。
  4. 现在点击"New Program"按钮。这将为你创建一个新的 UdonSharp 程序资源。
  5. 点击"Create Script"按钮并选择保存目标和脚本名称。

创建新的 UdonSharp 脚本时，你会得到两个文件：

  • 一个"UdonSharp Program Asset"文件。（创建后无需编辑此文件。）
  • 一个 .cs 文件。它包含 UdonSharpBehaviour 类，如下所示：
using UdonSharp;
using UnityEngine;
using VRC.SDKBase;
using VRC.Udon;

public class YourScriptName : UdonSharpBehaviour
{
    void Start()
    {
        
    }
}

在你选择的编辑器中编辑 UdonSharpBehaviour 并开始编程。你可以将 UdonSharpBehaviour 添加到场景中的任何 GameObject 上。

支持的 C# 特性​

UdonSharp 支持大多数 C# 基本语法：

  • 流程控制：if、else、while、for、do、foreach、switch、return、break、continue、三元运算符 (condition ? true : false)、??
  • 隐式和显式类型转换
  • 数组和数组索引器
  • 所有内置算术运算符
  • 条件短路 (true || CheckIfTrue()) 不会执行 CheckIfTrue()
  • typeof()
  • 带有 out 或 ref 参数的 Extern 方法，例如 Physics.Raycast() 的多种变体
  • 带参数和返回值的用户定义方法，支持 out/ref、扩展方法和 params
  • 用户定义属性
  • 静态用户方法
  • UdonSharpBehaviour 继承、虚方法等
  • 带参数的 Unity/Udon 事件回调。例如，注册带 VRCPlayerApi 参数的 OnPlayerJoined 事件是有效的。
  • 字符串插值
  • 字段初始化器
  • 锯齿数组
  • 引用其他自定义 UdonSharpBehaviour 类、访问字段和调用其方法
  • 通过 [RecursiveMethod] 特性支持递归方法调用

与 Unity/C# 特性的差异​

UdonSharp 不遵循任何版本的 C# 语言规范。某些 C# 特性未实现或无法工作。

  • 为了获得创建 UdonSharp 脚本的最佳体验，请使脚本继承自 UdonSharpBehaviour 而不是 MonoBehaviour。
  • 更改序列化为 Behaviour 字段的 enabled 状态在 behaviour 是 UdonSharpBehaviour 组件时无效。应改为使用自定义 U# 脚本的类型序列化该字段。
  • Udon 和 UdonSharp 目前仅支持数组 [] 集合和数据容器。泛型集合如 List<T> 尚不支持。
  • 字段初始化器在编译时求值。如果有依赖于场景中其他对象的初始化逻辑，应使用 Start。
  • 对要跨网络同步的字段使用 [UdonSynced] 特性。
  • 由于 UdonVM 的限制，数值转换会检查溢出。
  • 由 .GetType() 返回的变量的内部类型并不总是符合你的预期，因为 U# 抽象了一些类型以便它们在 Udon 中工作。例如，任何锯齿数组类型将返回 object[] 类型，而不是像二维 int 锯齿数组的 int[][]。

示例脚本​

旋转立方体演示​

每秒将附加的对象旋转 90 度。

using UnityEngine;
using UdonSharp;

public class RotatingCubeBehaviour : UdonSharpBehaviour
{
    private void Update()
    {
        transform.Rotate(Vector3.up, 90f * Time.deltaTime);
    }
}

其他示例​

  • VRChat Worlds SDK 在 Assets/UdonSharp/UtilityScripts 中包含 UdonSharp 示例。
    • 如果不使用这些脚本，可以安全删除。
  • 更多示例脚本，请查看 GitHub wiki 示例 或 U# 附带的 Examples 文件夹。
  • 访问 VRChat Creator Hub 与其他创作者交流并查看他们的示例。

常见问题​

UdonSharp 是否支持所有 Udon 功能？​

是的。只要 Udon 支持，UdonSharp 就支持。你可以查看类暴露树了解 UdonSharp 可以访问的所有内容。

可以在一个 GameObject 上拥有多个 UdonSharp UdonBehavior 吗？​

可以。

我从零开始需要学习 C# 教程。UdonSharp 中哪些常见的 C# 特性不支持？​

如果你正在学习 UdonSharp 且不熟悉 C#，可能会遇到一些在 Udon 和 UdonSharp 中尚不支持的常用技术。这些包括但不限于以下内容：

  • 泛型类（Class<T>）和泛型非静态方法
  • 接口
  • 方法重载
  • 属性