13. 按一下,灯亮了
本章给第二部房间里的 GlowBall 配一个灯光开关。按钮收到 Interact 事件后,脚本翻转目标 Light 组件的 enabled 状态。
Interact 的组件和输入条件
Section titled “Interact 的组件和输入条件”一个可交互按钮需要:
- GameObject 上有启用的 Collider,用于命中检测。
- 同一 GameObject 上有可运行的 Udon Behaviour,程序实现
Interact,且没有禁用交互。 - 玩家能指向该 Collider,并处于允许交互的距离内。
Interaction Text 是动作提示,帮助玩家判断操作结果;它不是启用交互的开关。不能把「没有填自定义提示」直接当成事件不执行的原因。
Interact、Pickup、Use 的区别
Section titled “Interact、Pickup、Use 的区别”- Interact:对场景中的交互对象执行操作,例如按钮调用
Interact()。 - Pickup / Grab:拿起带
VRC Pickup的物体,拿起时触发OnPickup()。 - Use:使用已经拿在手里的物体,触发
OnPickupUseDown()/OnPickupUseUp()。
官方默认桌面键鼠操作中,鼠标左键用于 Interact / Pickup;持有支持 Use 的物体时,左键用于 Use,右键用于放下。V 对应麦克风操作,不是这里的交互键。VR 的 Use 通常映射到扳机,Grab 通常映射到握把,但控制器型号、Auto Hold 设置和用户绑定都会影响实际操作。测试时以 VRChat 当前的控制设置和设备提示为准,脚本使用事件名,不检测一个假定通用的物理按键。官方键鼠操作和输入事件文档分别列出操作与输入映射。
第一步:在房间里放一个开关
Section titled “第一步:在房间里放一个开关”打开场景。如果已完成 C# 章的 Button_LightSwitch,可将该按钮重命名为 LampSwitch 并复用。没有这个按钮时,在 Hierarchy 空白处右键 3D Object → Cube,命名 LampSwitch。设置:
Position -1.5, 1.0, -2Rotation 0, 0, 0Scale 0.3, 0.3, 0.1这会得到一个扁方块按钮。若要贴墙放置,根据已经创建的墙的位置调整坐标和朝向,让按钮露出墙面,玩家能走近并指向它。前方有其他 Collider 遮挡时,命中检测可能先碰到遮挡物。
可按第 9 章的方法新建 Mat_Switch_Brass,把 Albedo 设为 #C49A6C 并赋给按钮,使它与墙面颜色有区别。材质不影响 Interact 的执行。
第二步:创建灯光开关脚本
Section titled “第二步:创建灯光开关脚本”在 Assets/Scripts/ 查找 LampToggle.cs。C# 章已创建过它时,打开并复用同一份脚本及其关联的 Udon Program Asset,不再新建同名类。不存在时,右键 Create → U# Script,命名 LampToggle。核对或修改内容如下:
using UdonSharp;using UnityEngine;
public class LampToggle : UdonSharpBehaviour{ public Light targetLight;
public override void Interact() { if (targetLight == null) return; targetLight.enabled = !targetLight.enabled; }}保存后回 Unity,等待编译完成,检查 Console 是否有编译错误。
UdonSharpBehaviour是脚本继承的基类。public Light targetLight在 Inspector 中提供一个Light引用槽。public override void Interact()实现 UdonSharp 的交互事件。targetLight == null表示未引用到有效的灯;此时返回,避免访问空引用。!targetLight.enabled对布尔值取反,亮着的灯关闭,关闭的灯开启。
UdonSharp 的 VRChat 事件使用基类提供的签名,例如 public override void Interact();Start、Update 则使用 Unity 生命周期方法的写法。事件名、大小写和参数必须与文档一致,不能用一个同名的普通方法代替事件声明。
第三步:挂脚本并绑定目标
Section titled “第三步:挂脚本并绑定目标”选中 LampSwitch,检查是否已有 LampToggle。复用 C# 章按钮时保留已有脚本组件,不再重复添加;只有缺少时,才把 LampToggle.cs 拖到 Inspector,或通过 Add Component 添加 Lamp Toggle。
把带 Light 的 GlowBall 拖到 Target Light 槽中。Unity 能从拖入的 GameObject 上匹配所需组件;也可以直接拖入它的 Light 组件。如果该物体没有 Light,应选择实际挂有灯光组件的物体。
本例切换的是灯光组件,不会关闭 GlowBall 的 Mesh Renderer,也不会改变材质的 Emission。若球体材质本身发亮,关灯后球面仍可能可见;若环境亮度来自已经烘焙的光照,也不能用关闭运行时 Light 来移除那份烘焙贡献。测试开关时使用 Realtime 灯光,观察它照亮的附近表面。
第四步:配置 Collider 和交互提示
Section titled “第四步:配置 Collider 和交互提示”保留 Cube 自带的 Box Collider,确认它启用。本章按钮采用未勾选 Is Trigger 的普通 Collider。
在 Udon Behaviour 中设置 Interaction Text:
开关灯 / Toggle light玩家指向可交互物体时,VRChat 的交互界面显示这段作者填写的文字。桌面与 VR 的提示布局不同,不应把它描述成固定显示在玩家或物体头顶。
提示文字与本地化
Section titled “提示文字与本地化”Interaction Text 是一个字符串,不是自动翻译服务。写入中文不会自动生成英文;客户端菜单切换语言,也不等于世界作者填写的任意文字被翻译。
可按实际受众选择:
- 短提示直接使用双语,例如
开关灯 / Toggle light、坐下 / Sit。 - 在按钮旁加图标或说明牌,用于补充动作含义;文字仍由作者提供。
- 文本较多时,由作者准备翻译表和语言选择界面,在本地更新
InteractionText。SDK 提供的GetCurrentLanguage能读取本地用户选择的界面语言,例如en、ja、zh-CN,但不会生成译文,也不代表该用户只懂这一种语言。语言未收录时,需要预设回退文本。
本章使用双语提示,不添加语言切换脚本。运行时修改 Interaction Text 和读取语言的能力分别见官方 Udon 更新说明与Player API:Language。
把 Proximity 设为 2。它参与交互距离判定,不是以按钮 Transform 为中心的固定两米球:射线判定使用射线起点到 Collider 命中点的距离,桌面模式还有与 Avatar 尺寸有关的额外触及补偿。VR 靠近物体时还存在手部 Hover 判定。因此不能承诺「退到三米外一定没有提示」。详细规则见官方 Proximity Rules。
第五步:Build & Test
Section titled “第五步:Build & Test”打开 VRChat SDK → Show Control Panel → Builder,运行 Build & Test。
- 走近
LampSwitch,对准按钮,检查提示是否显示开关灯 / Toggle light。 - 发起一次 Interact,观察目标实时灯的照明是否关闭;再次操作应恢复。
- 从近到远移动,记录当前 Avatar 和输入模式下提示消失的位置。
- 回 Unity 把
Proximity改为0.5,重新构建,比较有效交互范围。
结果不符合预期时
Section titled “结果不符合预期时”- 没有高亮或提示:检查按钮与 Collider 是否启用、程序是否编译并挂到同一物体、是否禁用了交互、距离和前方遮挡是否符合条件。
- 有提示但灯不变:检查
Target Light是否指向正确组件。示例的空引用判断会直接返回,所以引用为空时不一定有运行时错误。 - 灯关闭但球或房间仍然亮:区分实时灯、材质自亮、其他灯和烘焙光照。
- 编译失败:按 Console 中的文件名与行号检查类名、事件签名和语法,再构建测试。
本地状态的范围
Section titled “本地状态的范围”Interact 在操作玩家的客户端执行。这段脚本没有发送网络事件或同步字段,因此它只修改这个客户端的 Light.enabled。
在可进行多人测试的实例中,A 操作开关后,A 的灯变了;B 的灯不会因为这段代码自动改变。需要公共灯光状态时,必须另行设计状态同步、写入权限与加入实例时的初始化;本例不具备这些行为。
- 复制一个
LampSwitch,把新按钮的Target Light指向另一盏灯,检查两个引用是否分别生效。 - 让灯开启三秒后关闭:保留 targetLight 引用,在 Interact 中先判空再设置
enabled = true,安排三秒后的公开回调,在回调中判空并设为 false。可参照 DelayedMessage 的完整延迟入口与 waiting 锁,将两处日志分别换成开灯和关灯。此版本等待期间忽略新点击;测试约一秒时再点,不能把它误解为重新计时三秒。 - 加
int pressCount字段,每次 Interact 先加一;第三次把targetLight.color改为红色并跳过本次 enabled 翻转,其余次数仍切换灯。先使用pressCount == 3,再在副本中改成pressCount % 3 == 0,从重新进入场景的零次开始,记录第 1–6 次的次数、颜色与启用状态。前者只在第三次满足,后者每三次满足;只变颜色不保证一盏关闭的灯可见。 - 把目标改为
MeshRenderer,翻转它的enabled。结果是隐藏网格,不会自动禁用 Collider 或整个 GameObject。
- Collider 提供可命中的范围。
Interact定义操作发生时的入口。Interaction Text提供动作提示。targetLight指定操作对象。enabled的取反决定本次操作结果。
- VRChat Creator Docs:Event Nodes
- VRChat Creator Docs:Input Events
- VRChat Docs:Keyboard and Mouse
- VRChat Creator Docs:VRC Pickup / Proximity Rules
- VRChat Creator Docs:Player API / Language
- VRChat 2021.4.2:Interaction Text 的 Udon 接口
- UdonSharp Docs:Examples
原稿参考来源(第三方,保留来源记录):