跳转到内容

11. 刚好够用的 C#

约 40 分钟 内容:基础 动手章

程序流程中的变量、条件和方法,可以用 C# 语法表达。本章展示 UdonSharp 使用的基础写法,并区分完整脚本与语法片段。

C# 是语言,Unity 与 Udon 提供各自的 API 和运行条件。因此,一段语法正确的普通 C# 代码,也可能因为使用了未开放的 API 而无法编译为 Udon 程序。

LampToggle.cs
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 对布尔值取反,赋值后灯的启用状态翻转。
  1. 在 Project 的 Assets/Scripts 中右键 Create → U# script,创建 LampToggle.cs 及配套程序资产。
  2. 用代码编辑器打开 .cs,填入完整脚本。文件名与类名保持一致,保存并等待编译结束。
  3. 创建可见 Cube 作为 Button_LightSwitch,保留 Collider,把脚本挂在这个物体上。
  4. 把带有 Light 的 GlowBall 拖进 Target Light 字段。
  5. 确认被控制的灯是本例的 Realtime Light;设置可辨认的交互提示,例如 灯光 / Light。
  6. 在 ClientSim 或 Build & Test 中对准按钮并执行客户端提示的交互操作。
  7. 第一次交互应翻转 Light 状态,第二次应恢复;清空引用的测试副本则应输出警告而不修改灯光。

Interact 需要目标物体满足 Collider、Udon Behaviour 和交互距离等条件。它不是某个固定键盘键的别名,也不是 Pickup 或手持物品 Use 事件。这个脚本没有配置网络同步,只改变本地场景的灯光状态。

分号 ; 结束变量声明、赋值和方法调用等语句:

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);
GameObjectUnity 对象引用public GameObject door;
LightLight 组件引用public Light mainLight;
TransformTransform 组件引用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 是不同名称。本书示例中类和方法采用大驼峰,字段与局部变量采用小驼峰。命名约定用于保持一致,不是语法强制要求。

字段属于类,局部变量属于方法或代码块。以下是完整的计数器示例:

Counter.cs
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 (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 执行十次,输出从 0 到 9:

for (int i = 0; i < 10; i++)
{
Debug.Log("索引 = " + i);
}

三个部分分别是初始化、继续条件、每轮结束后的更新。i++ 将计数器加一。

while 在每轮执行前检查条件:

int remaining = 3;
while (remaining > 0)
{
Debug.Log("剩余次数 = " + remaining);
remaining--;
}

这里每轮减一,三轮后条件为假,循环结束。循环不会自动跨帧;用循环反复移动门,会在同一次调用中完成全部计算,而不是生成逐帧动画。

下面三个方法是类内片段,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

参数属于这次调用,改变参数并不等于修改其他字段,具体取决于传递的是值还是对象引用及方法做了什么。

方法调用条件
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 输出信息,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 会在资源刷新时编译;项目设置可能影响自动刷新时机。

每帧大量打印会增加日志和运行开销。观察连续数据时,按时间或帧数限频,并在诊断完成后删除不需要的输出。

DoorController.cs
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 在两个目标高度间选择。

测试连续交互、移动中反向,以及缺少门板引用的情况。这个例子说明本地状态与逐帧更新,不包含网络同步、夹人检测或完整门体设计。

Inspector 引用让脚本明确控制哪个目标,不要求用名称在运行时搜索。以下是完整示例:

ButtonOpensDoor.cs
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 属于运行时查找,有命名、活动状态和成本等约束,不能与已配置的直接引用当作完全相同的方式。

类型与变量 类型约束、默认值、局部变量赋值
字段与序列化 public、private、SerializeField
条件与循环 if、else、for、while、结束条件
方法 参数、返回值、访问范围
事件 Start、Update、Interact、玩家通知
类 继承 UdonSharpBehaviour
对象引用 Inspector 配置、有效性检查
诊断 事件日志、状态日志、编译与运行错误