跳转到内容

13. 按一下,灯亮了

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

本章给第二部房间里的 GlowBall 配一个灯光开关。按钮收到 Interact 事件后,脚本翻转目标 Light 组件的 enabled 状态。

一个可交互按钮需要:

  1. GameObject 上有启用的 Collider,用于命中检测。
  2. 同一 GameObject 上有可运行的 Udon Behaviour,程序实现 Interact,且没有禁用交互。
  3. 玩家能指向该 Collider,并处于允许交互的距离内。

Interaction Text 是动作提示,帮助玩家判断操作结果;它不是启用交互的开关。不能把「没有填自定义提示」直接当成事件不执行的原因。

  • Interact:对场景中的交互对象执行操作,例如按钮调用 Interact()。
  • Pickup / Grab:拿起带 VRC Pickup 的物体,拿起时触发 OnPickup()。
  • Use:使用已经拿在手里的物体,触发 OnPickupUseDown() / OnPickupUseUp()。

官方默认桌面键鼠操作中,鼠标左键用于 Interact / Pickup;持有支持 Use 的物体时,左键用于 Use,右键用于放下。V 对应麦克风操作,不是这里的交互键。VR 的 Use 通常映射到扳机,Grab 通常映射到握把,但控制器型号、Auto Hold 设置和用户绑定都会影响实际操作。测试时以 VRChat 当前的控制设置和设备提示为准,脚本使用事件名,不检测一个假定通用的物理按键。官方键鼠操作和输入事件文档分别列出操作与输入映射。

打开场景。如果已完成 C# 章的 Button_LightSwitch,可将该按钮重命名为 LampSwitch 并复用。没有这个按钮时,在 Hierarchy 空白处右键 3D Object → Cube,命名 LampSwitch。设置:

Position -1.5, 1.0, -2
Rotation 0, 0, 0
Scale 0.3, 0.3, 0.1

这会得到一个扁方块按钮。若要贴墙放置,根据已经创建的墙的位置调整坐标和朝向,让按钮露出墙面,玩家能走近并指向它。前方有其他 Collider 遮挡时,命中检测可能先碰到遮挡物。

可按第 9 章的方法新建 Mat_Switch_Brass,把 Albedo 设为 #C49A6C 并赋给按钮,使它与墙面颜色有区别。材质不影响 Interact 的执行。

在 Assets/Scripts/ 查找 LampToggle.cs。C# 章已创建过它时,打开并复用同一份脚本及其关联的 Udon Program Asset,不再新建同名类。不存在时,右键 Create → U# Script,命名 LampToggle。核对或修改内容如下:

LampToggle.cs
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 生命周期方法的写法。事件名、大小写和参数必须与文档一致,不能用一个同名的普通方法代替事件声明。

选中 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 的提示布局不同,不应把它描述成固定显示在玩家或物体头顶。

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。

打开 VRChat SDK → Show Control Panel → Builder,运行 Build & Test。

  1. 走近 LampSwitch,对准按钮,检查提示是否显示 开关灯 / Toggle light。
  2. 发起一次 Interact,观察目标实时灯的照明是否关闭;再次操作应恢复。
  3. 从近到远移动,记录当前 Avatar 和输入模式下提示消失的位置。
  4. 回 Unity 把 Proximity 改为 0.5,重新构建,比较有效交互范围。
  • 没有高亮或提示:检查按钮与 Collider 是否启用、程序是否编译并挂到同一物体、是否禁用了交互、距离和前方遮挡是否符合条件。
  • 有提示但灯不变:检查 Target Light 是否指向正确组件。示例的空引用判断会直接返回,所以引用为空时不一定有运行时错误。
  • 灯关闭但球或房间仍然亮:区分实时灯、材质自亮、其他灯和烘焙光照。
  • 编译失败:按 Console 中的文件名与行号检查类名、事件签名和语法,再构建测试。

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 的取反决定本次操作结果。

原稿参考来源(第三方,保留来源记录):