11. 刚好够用的 C#
程序流程中的变量、条件和方法,可以用 C# 语法表达。本章展示 UdonSharp 使用的基础写法,并区分完整脚本与语法片段。
C# 是语言,Unity 与 Udon 提供各自的 API 和运行条件。因此,一段语法正确的普通 C# 代码,也可能因为使用了未开放的 API 而无法编译为 Udon 程序。
一段完整的灯光开关脚本
Section titled “一段完整的灯光开关脚本”using UdonSharp;using UnityEngine;
public class LampToggle : UdonSharpBehaviour{ public Light targetLight;
public override void Interact() { if (targetLight == null) { Debug.LogWarning("LampToggle:Target Light 未配置"); return; }
targetLight.enabled = !targetLight.enabled; }}using导入命名空间,允许使用其中类型的简写名称;它不会自行安装库。class LampToggle声明类。: UdonSharpBehaviour表示继承 UdonSharp 的行为基类。public Light targetLight是字段,类型为 Light,保存对具体灯组件的引用。Interact()是对这个对象发生本地交互时调用的事件方法。if检查引用是否为空;为空时记录日志,并用return结束本次调用。!targetLight.enabled对布尔值取反,赋值后灯的启用状态翻转。
创建、挂载与测试
Section titled “创建、挂载与测试”- 在 Project 的
Assets/Scripts中右键Create → U# script,创建LampToggle.cs及配套程序资产。 - 用代码编辑器打开
.cs,填入完整脚本。文件名与类名保持一致,保存并等待编译结束。 - 创建可见 Cube 作为
Button_LightSwitch,保留 Collider,把脚本挂在这个物体上。 - 把带有 Light 的
GlowBall拖进Target Light字段。 - 确认被控制的灯是本例的 Realtime Light;设置可辨认的交互提示,例如
灯光 / Light。 - 在 ClientSim 或
Build & Test中对准按钮并执行客户端提示的交互操作。 - 第一次交互应翻转 Light 状态,第二次应恢复;清空引用的测试副本则应输出警告而不修改灯光。
Interact 需要目标物体满足 Collider、Udon Behaviour 和交互距离等条件。它不是某个固定键盘键的别名,也不是 Pickup 或手持物品 Use 事件。这个脚本没有配置网络同步,只改变本地场景的灯光状态。
语句、代码块和注释
Section titled “语句、代码块和注释”分号 ; 结束变量声明、赋值和方法调用等语句:
int score = 0;score = score + 1;Debug.Log(score);不是所有行都以分号结束,类、方法和 if 的代码块使用大括号。
大括号限定类、方法或控制流块的范围,缩进帮助阅读,但不能替代括号。
注释供读者阅读,不作为程序指令执行:
int score = 0; // 当前分数/* 这一段文字说明字段用途,编译器不会执行它。 */临时注释代码可以缩小问题范围,但测试时需记录停用了哪一段,避免把删减后的行为误认作完整结果。
C# 使用静态类型。显式声明写成 类型 名字 = 初始值;;也支持 var 根据初始表达式推断类型,推断后并不是任意类型都能赋进去。
| 类型 | 含义 | 示例 |
|---|---|---|
int | 整数 | int score = 0; |
float | 单精度浮点数 | float speed = 1.5f; |
bool | 真或假 | bool isOpen = false; |
string | 文本 | string label = "Light"; |
Vector3 | 三个浮点分量,可表示位置、方向等 | Vector3 point = new Vector3(0, 0.2f, 0); |
GameObject | Unity 对象引用 | public GameObject door; |
Light | Light 组件引用 | public Light mainLight; |
Transform | Transform 组件引用 | public Transform target; |
Material | 材质资源引用 | public Material wallMaterial; |
带小数点的数值字面量默认是 double。写 1.5f 明确表示 float,避免把 double 隐式赋给 float 的类型错误。int x = 1.5f; 不成立;显式转换 (int)1.5f 得到 1,是向零截断,不是四舍五入。
字段和数组元素有默认值,例如数字 0、布尔 false、引用 null。方法内的局部变量必须在读取前被明确赋值,不能把字段的默认初始化规则直接套给所有变量。
private int score; // 字段默认值为 0
private void Start(){ int delta = 1; // 局部变量在使用前赋值 score = score + delta;}变量名区分大小写,health 与 Health 是不同名称。本书示例中类和方法采用大驼峰,字段与局部变量采用小驼峰。命名约定用于保持一致,不是语法强制要求。
字段、访问范围与序列化
Section titled “字段、访问范围与序列化”字段属于类,局部变量属于方法或代码块。以下是完整的计数器示例:
using UdonSharp;using UnityEngine;
public class Counter : UdonSharpBehaviour{ [SerializeField] private int score; [SerializeField] private int increment = 1;
public override void Interact() { int delta = increment; score = score + delta; Debug.Log("score = " + score); }}将 Counter 保存为对应 U# Script,挂到带 Collider 的测试 Cube,提示填 计数 / Count。Inspector 中 Score 设为 0、Increment 设为 2,进入 ClientSim 连续交互两次,Console 应依次输出 2、4。退出 Play Mode 后改 Increment,再启动比较;外部 Build & Test 则查对应客户端日志。
public决定其他代码的访问权限;符合序列化要求的 public 字段通常也在 Inspector 中显示。private限制类外直接访问,默认不显示在 Inspector。[SerializeField] private在保留私有访问范围的同时,让支持的字段被序列化并显示在 Inspector。
访问范围与序列化是两件事。并非任意类型或任意 public 成员都能保存;属性也不等同于序列化字段。
transform.position、Light.enabled 是 Unity API 的属性。可以通过赋值调用它们的设置逻辑,但它们并不是脚本自己声明的普通字段。
if 与 else
Section titled “if 与 else”以下片段假定相关字段已经声明并赋好引用:
if (score >= 10){ door.SetActive(false);}SetActive(false) 禁用整个 GameObject,不只是隐藏 Renderer;门的 Collider、组件运行及子物体也会受影响。若只要隐藏外观,应操作相应 Renderer。
两个分支的例子:
if (isDay){ sun.intensity = 1f;}else{ sun.intensity = 0.1f;}多个条件按顺序判断,命中一条后不再执行其他分支:
if (score < 0){ Debug.Log("分数无效");}else if (score < 10){ Debug.Log("尚未达到 10 分");}else{ Debug.Log("已达到 10 分");}| 运算符 | 含义 |
|---|---|
== / != | 相等 / 不相等 |
< / <= / > / >= | 大小比较 |
&& | 且 |
|| | 或 |
! | 布尔取反 |
单个 = 表示赋值,== 表示比较。! 是运算符,本身并不是 if 分支。
for 与 while
Section titled “for 与 while”下面的 for 执行十次,输出从 0 到 9:
for (int i = 0; i < 10; i++){ Debug.Log("索引 = " + i);}三个部分分别是初始化、继续条件、每轮结束后的更新。i++ 将计数器加一。
while 在每轮执行前检查条件:
int remaining = 3;while (remaining > 0){ Debug.Log("剩余次数 = " + remaining); remaining--;}这里每轮减一,三轮后条件为假,循环结束。循环不会自动跨帧;用循环反复移动门,会在同一次调用中完成全部计算,而不是生成逐帧动画。
方法、参数和返回值
Section titled “方法、参数和返回值”下面三个方法是类内片段,door 与 score 表示已配置字段:
// 无参数,无返回值private void HideDoor(){ if (door != null) { door.SetActive(false); }}
// 一个参数,无返回值private void SetScore(int newScore){ score = newScore; Debug.Log("score = " + score);}
// 两个参数,返回整数private int Add(int a, int b){ return a + b;}void 表示不返回值。返回类型为 int 的方法可以这样调用:
int total = Add(3, 5); // total 得到 8参数属于这次调用,改变参数并不等于修改其他字段,具体取决于传递的是值还是对象引用及方法做了什么。
事件方法的调用条件
Section titled “事件方法的调用条件”| 方法 | 调用条件 |
|---|---|
Start() | 行为首次开始运行时的初始化入口 |
Update() | 行为激活并运行时,每帧调用 |
Interact() | 本地玩家与对应可交互对象交互 |
OnPlayerJoined(VRCPlayerApi player) | 玩家加入通知;本地加入时也通知已在实例中的玩家 |
OnPlayerLeft(VRCPlayerApi player) | 玩家离开实例通知 |
Update 的次数取决于实际帧率,不是桌面固定 60 次或 VR 固定 90 次。
UdonSharp 的 Start、Update 使用 Unity 生命周期写法,不写 override;Interact、OnPlayerJoined、OnPlayerLeft 使用基类定义的事件签名,写成 public override。带 VRCPlayerApi 参数时还需引用 VRC.SDKBase 命名空间。
Debug.Log 与日志位置
Section titled “Debug.Log 与日志位置”Debug.Log 输出信息,Debug.LogWarning 输出警告。可以在事件入口和修改状态的位置分别记录:
public override void Interact(){ Debug.Log("Counter 收到 Interact"); score = score + 1; Debug.Log("score = " + score);}在 Unity 的 ClientSim 中运行时,查看 Window → General → Console。通过 Build & Test 运行在 VRChat 客户端中时,主要查看客户端输出日志及 SDK 提供的调试信息,不能假定消息一定直接出现在 Unity Console。
如果没有入口日志,检查事件触发条件;有入口日志却没有结果日志,检查中间语句和异常。保存 .cs 后,Unity 会在资源刷新时编译;项目设置可能影响自动刷新时机。
每帧大量打印会增加日志和运行开销。观察连续数据时,按时间或帧数限频,并在诊断完成后删除不需要的输出。
完整示例:逐帧移动门模型
Section titled “完整示例:逐帧移动门模型”using UdonSharp;using UnityEngine;
public class DoorController : UdonSharpBehaviour{ [SerializeField] private Transform doorPanel; [SerializeField] private float openHeight = 3f; [SerializeField] private float closeHeight = 0f; [SerializeField] private float speed = 2f;
private bool isOpening;
public override void Interact() { isOpening = !isOpening; }
private void Update() { if (doorPanel == null) return;
float targetY = isOpening ? openHeight : closeHeight; Vector3 pos = doorPanel.localPosition; pos.y = Mathf.MoveTowards(pos.y, targetY, speed * Time.deltaTime); doorPanel.localPosition = pos; }}这段代码把交互控制器与移动门板分开,避免门升起后连同唯一交互目标一起移出玩家可操作范围。
- 将脚本挂在固定的按钮物体上,按钮保留 Collider。
- 将独立门板的 Transform 拖进
Door Panel。 openHeight与closeHeight使用门板父级坐标,不是世界坐标。按实际尺寸设置,不让关闭位置落入地板。speed使用正数;父级缩放为1时,数值可按 Unity 单位每秒理解。Time.deltaTime把每帧位移换算为随时间变化的量。- 三元表达式
条件 ? 值A : 值B在两个目标高度间选择。
测试连续交互、移动中反向,以及缺少门板引用的情况。这个例子说明本地状态与逐帧更新,不包含网络同步、夹人检测或完整门体设计。
引用其他物体
Section titled “引用其他物体”Inspector 引用让脚本明确控制哪个目标,不要求用名称在运行时搜索。以下是完整示例:
using UdonSharp;using UnityEngine;
public class ButtonOpensDoor : UdonSharpBehaviour{ [SerializeField] private GameObject targetDoor;
public override void Interact() { if (targetDoor == null) { Debug.LogWarning("ButtonOpensDoor:Target Door 未配置"); return; }
targetDoor.SetActive(false); }}把脚本挂到独立按钮,门对象拖入 Target Door。交互后,门整体被禁用,按钮仍保留。这个操作没有定义再次启用门的逻辑。
Inspector 引用不依赖目标显示名称,目标改名后通常仍有效;删除或替换目标则需要重新检查。GameObject.Find 属于运行时查找,有命名、活动状态和成本等约束,不能与已配置的直接引用当作完全相同的方式。
本章内容索引
Section titled “本章内容索引”类型与变量 类型约束、默认值、局部变量赋值字段与序列化 public、private、SerializeField条件与循环 if、else、for、while、结束条件方法 参数、返回值、访问范围事件 Start、Update、Interact、玩家通知类 继承 UdonSharpBehaviour对象引用 Inspector 配置、有效性检查诊断 事件日志、状态日志、编译与运行错误