Unity XR-XR Interaction Toolkit开发使用方法（四）组件介绍（XR Controller）

Unity XR Controller 是 XR Interaction Toolkit 中负责管理 XR 设备输入 的核心组件，用于将物理设备（如手柄、手部追踪传感器）的输入信号转化为 Unity 中的交互事件。它是连接硬件设备与虚拟交互逻辑的桥梁，支持跨平台输入映射和事件驱动设计，简化了多设备适配的复杂性。

原文翻译：

利用输入系统（Input System）中的动作，将追踪输入控制器设备上的特征值转化为XR交互状态（如选择状态）。此外，它还将追踪设备的当前姿态（Pose）值应用于游戏对象（GameObject）的变换属性上。

2、核心功能

设备输入抽象化

将不同 XR 设备（Oculus Touch、HTC Vive、Windows MR 等）的物理输入（按钮、摇杆、扳机键）统一映射为逻辑输入（如 Select、Activate、UI Press）。

支持通过 Unity Input System 配置输入动作，屏蔽底层硬件差异。

输入事件分发

实时监听设备输入状态（按下、释放、持续按压），触发对应事件（如 OnTriggerPressed、OnGripReleased）。

与 XR Interactor 组件协作，驱动交互行为（如抓取物体、发射射线）。

触觉反馈控制

提供接口发送震动指令，实现手柄的触觉反馈（如抓取物体时震动）。

支持调节震动强度、持续时间和频率。

姿态追踪

获取设备的位置和旋转信息（通过 Tracked Pose Driver 组件），实时更新手柄或手部模型的位置。

3、组件配置详解

在 Inspector 面板中，XR Controller 的关键配置如下：

1.追踪设置（Tracking）

Update Tracking Type	在帧内，控制器采样追踪输入所花费的时间。
Update	将Update Tracking Type设置为“Update”，以仅在`MonoBehaviour` `Update`期间采样追踪输入。
Before Render	将Update Tracking Type设置为“Before Render”，以仅在渲染前立即的步骤期间采样追踪输入。
Update And Before Render	将Update Tracking Type设置为“Update And Before Render”，以在帧内的上述两个时间点都采样追踪输入。
Enable Input Tracking	是否为此控制器启用输入姿态追踪。启用后，Unity会每帧读取控制器设备的当前追踪姿态输入。您可以禁用此功能，以便手动驱动控制器状态，而不是读取当前输入，例如在播放录制的姿态输入时。
Position Action
Use Reference	启用以引用使用随附字段外部定义的动作。
Reference	用于此GameObject的位置追踪的输入系统动作。必须是Vector3Control控件。
Rotation Action
Use Reference	启用以引用使用随附字段外部定义的动作。
Reference	用于此GameObject的旋转追踪的输入系统动作。必须是QuaternionControl控件。
Is Tracked Action
Use Reference	启用以引用使用随附字段外部定义的动作。
Reference	在更新此GameObject的位置和旋转时读取“被追踪”状态的输入系统动作；未设置时，回退到驱动位置或旋转动作的追踪设备的被追踪状态。必须是具有按钮式交互或ButtonControl控件的动作。
Tracking State Action
Use Reference	启用以引用使用随附字段外部定义的动作。
Reference	在更新此GameObject的位置和旋转时读取追踪状态的输入系统动作；未设置时，回退到驱动位置或旋转动作的追踪设备的追踪状态。必须是IntegerControl控件。

2. 输入动作绑定（Input Actions）

Enable Input Actions	是否为控制器启用了XR交互事件的输入。当启用时，Unity会在每一帧读取控制器设备的当前输入。您可以禁用此功能，以便手动驱动控制器的状态，而不是从读取当前输入中获取，例如在回放录制的输入时。
Select Action
Use Reference	启用后，可使用伴随字段引用外部定义的动作。
Reference	用于选择可交互对象（Interactable）的输入系统动作。必须为具有按钮式交互或ButtonControl控制的动作。
Select Action Value	可选，未设置时使用Select Action
Use Reference	启用后，可通过随附的字段引用外部定义的动作。
Reference	如果不同，则为读取选择动作浮点值的输入系统动作。必须是一个AxisControl或Vector2Control控制。
Activate Action
Use Reference	字段启用引用后外部，定义可通过的动作。
Reference	用于激活选定可交互对象的输入系统动作。必须是一个具有按钮式交互或ButtonControl控制的动作。
Activate Action Value	可选，未设置时使用Activate Action
Use Reference	启用后，可通过随附的字段引用外部定义的动作。
Reference	如果不同，则为读取激活动作浮点值的输入系统动作。必须是一个AxisControl或Vector2Control控制。
UI Press Action	可选，当启用与UI游戏对象的交互时，由XR射线交互器使用
Use Reference	启用后，可通过随附的字段引用外部定义的动作。
Reference	用于画布UI交互的输入系统动作。必须是一个具有按钮式交互或ButtonControl控制的动作。
UI Press Action Value	可选，未设置时使用UI按压动作UI Press Action
Use Reference	启用后，可通过随附的字段引用外部定义的动作。
Reference	如果不同，则为读取UI按压动作浮点值的输入系统动作。必须是一个AxisControl或Vector2Control控制。
UI Scroll Action Value	可选，由XR Ray Interactor使用
Use Reference	启用后，可通过随附的字段引用外部定义的动作。
Reference	用于读取画布UI滚动值的输入系统动作。必须是一个AxisControl或Vector2Control控制。
Haptic Device Action
Use Reference	启用后，可通过随附的字段引用外部定义的动作。
Reference	用于识别发送触觉脉冲的设备的输入系统动作。可以是任何将具有驱动该动作的活跃控制的控制类型。
Rotate Anchor Action	可选，当启用锚点控制且旋转模式设置为随时间旋转时，由 XR Ray Interactor使用
Use Reference	启用后，可通过随附的字段引用外部定义的动作。
Reference	用于随时间旋转交互器的附着点的输入系统动作。必须是一个Vector2Control控制。使用x轴作为旋转输入。
Directional Anchor Rotation Action	可选，当启用锚点控制且旋转模式设置为匹配方向时，由XR Ray Interactor使用
Use Reference	启用后，可通过随附的字段引用外部定义的动作。
Reference	用于计算旋转交互器的附着点以匹配方向的角度的输入系统动作。必须是一个Vector2Control控制。方向角度计算为x/y的反正切函数。
Translate Anchor Action	可选，当启用锚点控制时，由XR Ray Interactor使用
Use Reference	启用后，可通过随附的字段引用外部定义的动作。
Reference	用于将交互器的附着点平移得更近或更远离交互器的输入系统动作。必须是一个Vector2Control控制。使用y轴作为平移输入。
Scale Toggle Action	可选，当启用锚点控制时，由XR Ray Interactor使用
Use Reference	启用后，可通过随附的字段引用外部定义的动作。
Reference	用于启用或禁用从缩放增量动作的读取的输入系统动作。必须是一个ButtonControl控制。按钮的按下状态将切换缩放状态。
Scale Delta Action	可选，当启用锚点控制时，由XR Ray Interactor使用
Use Reference	启用后，可通过随附的字段引用外部定义的动作。
Reference	用于为变换器提供缩放增量值的输入系统动作。必须是一个Vector2Control控制。使用y轴作为缩放输入。

3. 模型配置

Model Prefab	这是一个控制器模型的预制件（Prefab），用于展示此控制器，该行为会自动实例化这个预制件。在启动时，除非已经设置了`model`（见下文），否则此行为会自动实例化预制件的一个实例，并将其作为`modelParent`（见下文）的子对象。如果已经设置了`model`，则会忽略此值。
Model Parent	此行为在实例化模型预制件时所使用的变换（Transform）作为其父对象。如果尚未设置，则会在`Awake`方法中自动实例化并设置。设置此值不会自动销毁之前的对象。
Model	场景中控制器模型的实例。您可以将此设置为一个现有对象，而不是使用modelPrefab（见上文）。如果已设置，它应该引用此行为的一个子游戏对象，以便它随着控制器姿态的更新而更新。
Animate Model	是否根据交互事件对模型进行动画处理。当启用时，在选择或取消选择时会激活一个命名的动画触发器。

4、事件系统与脚本交互

XR Controller 通过事件和脚本接口暴露输入状态，开发者可通过以下方式响应输入：

1. 直接监听 Unity 事件

在 Inspector 面板中绑定事件回调：

OnSelectEntered / OnSelectExited：抓取开始/结束。
OnActivate / OnDeactivate：激活/取消激活。
OnHoverEntered / OnHoverExited：悬停开始/结束。

2. 通过脚本获取输入状态

using UnityEngine.XR.Interaction.Toolkit;

public class ControllerInputExample : MonoBehaviour
{
    public XRController leftController;
    
    void Update()
    {
        // 检测 Trigger 键是否按下
        if (leftController.inputDevice.TryGetFeatureValue(CommonUsages.triggerButton, out bool isTriggerPressed))
        {
            if (isTriggerPressed)
                Debug.Log("Trigger Pressed!");
        }

        // 获取摇杆二维输入
        if (leftController.inputDevice.TryGetFeatureValue(CommonUsages.primary2DAxis, out Vector2 joystickAxis))
        {
            Debug.Log($"Joystick: {joystickAxis}");
        }
    }
}

3. 触发触觉反馈

leftController.SendHapticImpulse(0.5f, 1f);

5、与其他组件的协作

与 XR Interactor 的关联

XR Controller 将输入事件传递给 XR Interactor（如按下 Trigger 键触发 Select 动作）。

例如：当用户按下手柄的 Trigger 键时，XR Direct Interactor 会尝试抓取附近的物体。

与 XR Interaction Manager 的协同

XR Interaction Manager 确保输入事件正确路由到目标 Interactable 对象。

例如：当多个手柄尝试抓取同一物体时，Interaction Manager 根据优先级裁决。

与 Tracked Pose Driver 的集成

Tracked Pose Driver 组件（通常附加在 Controller 对象上）负责更新设备姿态。

开发者可通过脚本覆盖姿态数据（如实现瞬移后的手柄位置修正）。

6、跨设备兼容性处理

输入动作抽象化

使用 Input Action Assets 定义跨平台输入逻辑（如将 Oculus 的 Trigger 键和 Vive 的 Grip 键统一映射为 Select 动作）。
示例配置（通过 Unity Editor）：
创建 Input Action Asset，定义 Select 动作为 <XRController>{LeftHand}/trigger。
为不同设备覆盖映射（如 Vive 映射为 grip）。

设备自动识别

XR Controller 在运行时自动检测连接的设备类型，并加载对应的输入配置。
通过 XRControllerState 获取当前设备状态（如是否已连接）。

回退策略

为不支持的功能（如手部追踪）提供默认行为（如切换为射线交互）。

7、实际应用示例

场景1：抓取并投掷物体

将 XR Controller 绑定到手柄模型。
添加 XR Direct Interactor 组件，设置 Select Action 为 Trigger 键。
监听 OnSelectExited 事件，在释放物体时施加速度：

interactor.onSelectExited.AddListener(ThrowObject);

void ThrowObject(XRBaseInteractable interactable)
{
    Rigidbody rb = interactable.GetComponent<Rigidbody>();
    rb.velocity = controller.velocity;
    rb.angularVelocity = controller.angularVelocity;
}

场景2：自定义UI交互

为手柄添加 XR Ray Interactor，设置 UI Press Action 为 Trigger 键。
在 Canvas 上添加 Tracked Device Graphic Raycaster，支持射线交互。
监听 OnUIPress 事件，实现按钮点击反馈：

controller.uiPressAction.action.performed += OnUIPressed;

void OnUIPressed(InputAction.CallbackContext context)
{
    Debug.Log("UI Button Pressed!");
}

8、性能优化与调试

减少输入轮询频率

避免在 Update 中频繁调用 TryGetFeatureValue，改为事件驱动。

触觉反馈优化

限制高频震动调用，避免设备性能下降。

调试工具

使用 XR Interaction Debugger 可视化输入状态和事件流。
打印输入设备信息：

Debug.Log($"Device: {controller.inputDevice.name}, Status: {controller.inputDevice.isValid}");

9、常见问题与解决

问题：手柄输入无响应

检查步骤：
确认设备已正确连接并被 Unity 识别（检查 XRController.inputDevice.isValid）。
验证 Input Action 的绑定路径是否正确（如 XRController{RightHand}/trigger）。
确保 XR Controller 的 Enable Input Tracking 和 Enable Input Actions 已启用。
问题：手柄模型位置偏移

解决：
调整 XR Controller 对象的本地坐标，或校准设备追踪原点。
问题：触觉反馈无效

排查方向：
确认设备支持触觉反馈（如 Oculus Touch）。
检查 SendHapticImpulse 的调用参数是否在合理范围内（强度 0~1）。