跳转到内容

15. 拿起来,丢出去

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

VRC Pickup 与同一物体上的 Collider、Rigidbody 一起提供抓取功能。OnPickup、OnDrop、OnPickupUseDown 分别处理拿起、放下、持有时使用的动作。

本章制作一个可抓取的发光小球:拿起时调高 Light 强度,放下时恢复,持有时用 Use 循环切换颜色。灯光代码只作用于当前客户端。

  1. Collider:定义可命中的形状与碰撞形状。
  2. Rigidbody:处理重力、速度和物理运动。是否反弹还取决于物理材质,添加刚体本身不保证弹跳。
  3. VRC Pickup:提供 VRChat 的抓取、持有和使用行为。

无需脚本也能拿起物体;脚本用于增加拿起、放下、使用时的反馈。

在场景里复制一份第二部的 GlowBall,命名 PickupBall。需要断开 Prefab 关联时,对这个副本右键 Prefab → Unpack Prefab;原物体保留。

修改场景中的 Prefab 实例可以产生实例覆盖,不会自动改掉所有实例。只有把修改应用到 Prefab 资源,才会影响使用该资源且没有相应覆盖的实例。本例 Unpack 是为了得到独立练习对象。

把 PickupBall 放在有地板的位置,例如 0, 1.2, 0。检查已有 Mesh Filter、Mesh Renderer、Sphere Collider 和 Light;Sphere 是创建时使用的原始体类型,不是额外的组件。

选中 PickupBall:

  1. 添加 Rigidbody,勾选 Use Gravity,取消 Is Kinematic,让放下的小球能落下。
  2. 保留启用的 Sphere Collider,本例取消 Is Trigger,以便与地面实体碰撞。按小球实际模型调整半径。
  3. 添加 VRC Pickup,确认它与上述两个组件位于同一 GameObject。
  4. 确认对象没有标为静态,并检查地面有实体 Collider。

设置交互字段:

Interaction Text 拿起 / Pick up
Use Text 切换颜色 / Change color
Pickupable 开启
Proximity 2
Orientation Any
Exact Gun None
Exact Grip None
Disallow Theft 关闭

Interaction Text 在指向/靠近 Pickup 时显示;Use Text 在持有时提示使用动作,且要求 Auto Hold 开启。自定义文字不会自动翻译,双语提示的设置原则见第 13 章。Proximity 有桌面触及补偿和 VR Hover 规则,不是固定从模型中心测距。

Allow Manipulation When Equipped 控制键鼠或手柄输入下的持有物体调整,并非专门开启 VR 手部旋转。启用时,官方列出的键鼠旋转键为 I/J/K/L/U/O;按项目需求选择是否允许。

先看 VRC Pickup 自身的 Version 选择器。它的 1.0 / 1.1 是组件行为版本,不是整个 Worlds SDK 的版本号。

  • Pickup 1.1:Auto Hold 是复选框。勾选后释放初次 Grab 仍保持持有,再次 Grab 或 Drop 才放下;不勾选则释放初次 Grab 时放下。
  • Pickup 1.0:Auto Hold 是下拉框。Yes 保持持有,No 松开即放下;旧选项 Sometimes 只对键盘、鼠标、Gamepad、Vive Wand 输入采用保持,Auto Detect 在相同输入条件外还要求 Gun/Grip 配置。旧资源可保留这些字段,但不能把它们当成所有版本的同一个默认值。

本章需要桌面玩家拿起后继续按 Use,因此明确开启 Auto Hold:1.1 勾选,1.0 选择 Yes。Any 是 Orientation 的值,不能填到 Auto Hold。版本与旧选项条件见官方 Versions。

Orientation 控制拿起时的对齐方式,Auto Hold 控制是否保持持有。更改其中一项不会代替另一项。

  • Any:不指定固定握姿,适合本例这样的球形物体,无需 Exact 锚点。
  • Gun:按 Exact Gun 对齐,适合要求固定指向的物体,例如手电筒或指示器;名字并不限制物体必须是枪。
  • Grip:按 Exact Grip 对齐,但 VR 与非 VR 的朝向规则不同,适合需要两种持握方向的物体,例如手杖。

Exact Gun / Exact Grip 填的是 Transform。锚点位置表示模型中的握持位置,旋转表示用于对齐的坐标系。只调旋转不能修正手握在错误位置的问题。

以手电筒为例:

  1. 在 Pickup 根物体下新建空子物体 GunAnchor,Scale 保持 1,1,1。
  2. 把它的局部 Position 移到希望手握住的把手位置;不要默认放在灯头或整个模型中心。
  3. 在 Scene 视图切为 Local 坐标,旋转锚点,使它的局部轴与模型的目标方向对应。
  4. 将 Orientation 设为 Gun,把 GunAnchor 拖入 Exact Gun。Grip 则建立 GripAnchor 并填入 Exact Grip。

使用 Pickup 的子 Transform,可让锚点随物体移动。官方不建议空置对应 Exact 槽或引用物体层级外的 Transform。

官方当前规定的轴向是:

模式对齐规则
GunExact Gun 的局部 +X 对准瞄准前方,+Z 朝上
Grip,VR先把 Exact Grip 的 +X 对准前方、+Z 朝上,再向前俯转 30°
Grip,非 VRExact Grip 的 +Z 对准前方,+X 朝下

这些是 Pickup 的具体约定,不能照一般 Transform「蓝色 +Z 就是所有握持模式的前方」来猜。依据是官方 Orientation Rules;位置字段也见官方 UdonSharp VRChat API。

  1. 在桌面模式拿起,检查握持点、模型前方以及模型是否挡住视线。
  2. 在 VR 中分别用左右手拿起,检查把手位置、朝向、相对控制器的倾斜。尤其要单独测试 Grip 的两种输入模式。
  3. 手握偏了:回 Unity 调锚点的局部 Position。方向反了或倾斜不对:调锚点局部 Rotation。
  4. 确认实际引用的是刚调整的锚点,保存场景,重新 Build & Test;只在编辑器改 Transform 不会更新已运行的外部客户端。
  5. 重复放下与拿起,确认每次对齐相同。记录组件版本、输入方式和所用 Avatar,避免把不同测试条件下的差异当作同一次设置结果。

本章小球保留 Any,锚点步骤用于有明确握把和前方的模型。

第三步:测试拿起、使用、放下

Section titled “第三步:测试拿起、使用、放下”

运行 Build & Test,走近 PickupBall:

  • 桌面默认键鼠:对准后左键拿起;Auto Hold 已开启,松开仍持有。持有后左键执行 Use,右键放下。不能把第二次左键统一写成放下。
  • VR:靠近或指向后执行 Grab,持有时执行 Use。Grab 通常是握把,Use 通常是扳机;具体操作由设备、绑定和 Auto Hold 决定。开启 Auto Hold 后,松开握把不一定放下,需执行 Drop 或再次 Grab。
  • 物理结果:放下后球受重力下落,与地面碰撞。VR 投掷与释放时的运动有关,Pickup 的投掷增强参数也会影响结果;桌面可按官方的 Right Click + F (Hold) 投掷操作测试,不要只凭鼠标转动速度推断抛出方式。

若小球不可抓取,检查三个组件是否同物体、Collider 是否启用、Pickupable 和玩家抓取权限、可触及距离及遮挡。若球穿过地面,检查双方 Collider、碰撞层、刚体设置与移动速度。

输入依据见官方键鼠操作和Input Events。

在 Assets/Scripts/ 新建 PickupGlow,内容为:

PickupGlow.cs
using UdonSharp;
using UnityEngine;
public class PickupGlow : UdonSharpBehaviour
{
public Light targetLight;
[Tooltip("待机和被抓起时的两档亮度")]
public float restIntensity = 1.0f;
public float heldIntensity = 3.5f;
[Tooltip("Use 键按下后会循环切换的几种颜色")]
public Color[] colors;
private int colorIndex = 0;
private void Start()
{
if (targetLight != null)
{
targetLight.intensity = restIntensity;
if (colors != null && colors.Length > 0)
{
targetLight.color = colors[colorIndex];
}
}
}
public override void OnPickup()
{
if (targetLight != null)
{
targetLight.intensity = heldIntensity;
}
}
public override void OnDrop()
{
if (targetLight != null)
{
targetLight.intensity = restIntensity;
}
}
public override void OnPickupUseDown()
{
if (colors == null || colors.Length == 0) return;
if (targetLight == null) return;
colorIndex = (colorIndex + 1) % colors.Length;
targetLight.color = colors[colorIndex];
}
}

把脚本挂到 PickupBall,将它的 Light 拖到 Target Light。Colors 的 Size 设为 3,依次填写橙黄 #FFB347、青蓝 #6EE7F9、粉紫 #F472B6。

脚本在 Start 中应用第一种颜色与待机强度。Build & Test 的预期是:

  • 开始时:第一种颜色,强度 1.0。
  • 拿起时:强度变为 3.5。
  • 每次 Use:切到数组的下一种颜色,到末尾后回到第一种。
  • 放下时:强度恢复 1.0,颜色保留当前值,并不会恢复初始颜色。

这些值控制 Light,不会同时修改网格材质。需要球体表面也变色时,需另行更新材质颜色或 Emission。

事件入口包括:

OnPickup 本地玩家拿起物体
OnDrop 本地玩家放下物体
OnPickupUseDown 本地玩家持有物体时按下 Use
OnPickupUseUp 本地玩家持有物体时释放 Use

事件方法按文档写 public override。OnPickupUseDown / Up 在桌面模式要求开启 Auto Hold。Interact 是对场景交互对象的操作,不能当作手持物体的 Use 回调。官方事件定义

本地物理小球可用明确的高度条件复位。创建另一个脚本 PickupReset,也挂到 PickupBall:

PickupReset.cs
using UdonSharp;
using UnityEngine;
using VRC.SDKBase;
public class PickupReset : UdonSharpBehaviour
{
public float resetBelowY = -10f;
private Vector3 spawnPosition;
private Quaternion spawnRotation;
private Rigidbody body;
private VRC_Pickup pickup;
private void Start()
{
spawnPosition = transform.position;
spawnRotation = transform.rotation;
body = GetComponent<Rigidbody>();
pickup = GetComponent<VRC_Pickup>();
}
private void Update()
{
if (transform.position.y >= resetBelowY) return;
if (pickup != null && pickup.IsHeld) return;
transform.SetPositionAndRotation(spawnPosition, spawnRotation);
if (body != null)
{
body.velocity = Vector3.zero;
body.angularVelocity = Vector3.zero;
}
}
}

resetBelowY 使用世界坐标,应低于正常活动地面。记录的出生位置也必须高于这条界限。代码缓存组件引用,避免每次检测重新查找;持有时不强行复位,放下并越界后回到启动位置并清空速度。

此脚本针对未加 Object Sync 的本地练习物体。场景描述器也有 Respawn Height Y 与 Object Behaviour At Respawn,用于跌出世界的对象处理。自定义阈值应与它们协调,否则另一套复位/销毁规则可能先执行。

在场景副本中找一块允许小球落下的位置,确保复位高度高于 Scene Descriptor 的跌出世界处理高度,出生位置又高于复位高度。保存后重新 Build & Test:

  1. 将小球丢到地板外,让它降到阈值以下,检查是否返回启动时的位置和朝向,而不是停在越界处。
  2. 检查它返回后没有保留先前的线速度或旋转速度。
  3. 若测试路线允许持球经过阈值以下,确认持有时不被强制拉走,放下后才复位。
  4. 暂时停用 PickupReset 再测试一次,区分自定义复位与 Scene Descriptor 处理;完成后恢复组件设置。编辑器拖动物体不能替代外部客户端里的这一测试。

VRC Object Sync 同步位置、旋转、重力和 Kinematic 状态。它提供 Respawn() 方法回到原始出生位置;Allow Collision Ownership Transfer 的作用是碰撞时允许所有权转移,并不是打开自动复位。不要把这两个功能绑定成同一开关。

添加 Object Sync 不会自动同步本例的灯光强度和颜色。物理对象同步后,也不能继续让每个客户端无条件运行上述复位写入;复位需要遵循对象所有权。这里保留本地物理测试配置。

将已验证的 PickupBall 拖到 Assets/Prefabs/。创建变体时可复用 Collider、Rigidbody、Pickup 和脚本配置,再调整模型与颜色。更换模型后重新核对 Collider 尺寸、重心和握持锚点。

  • 添加 AudioSource clickSound,在 OnPickup 中判空后调用 Play(),让拿起动作带有音效。
  • 在 OnDrop 中对 Rigidbody 调用 AddForce,比较添加冲量与只保留投掷速度的结果,并明确所选 ForceMode。
  • 将颜色分成两组,用布尔字段选择当前数组。切换数组时检查长度并重置或限制 colorIndex,避免访问越界。

Collider 与 Rigidbody 提供形状和物理行为,VRC Pickup 提供抓取配置,Exact 锚点控制指定模式的持握对齐。事件脚本连接本地操作与灯光反馈,复位脚本处理明确的越界条件。每项功能有各自的状态与测试条件。

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