开发

在 Unreal Engine 中设置手势追踪

更新时间: 2026年4月14日

前提条件

如果您之前没有在 Unreal 引擎中实现输入运动控制器功能，请参阅 Unreal 引擎的运动控制器组件设置⁠。

开始在应用中实现手势追踪功能之前，请参阅手势追踪设计指南，了解在虚拟现实中使用手势作为输入源时涉及的术语、最佳实践和互动模型。

查看以下商店指南，了解如何实现手势追踪：

VRC.Quest.Input.5：手部模型必须以正确的位置和朝向进行渲染，且动画效果必须正常显示

VRC.Quest.Input.7：应用必须能适当地处理输入在控制器和手势之间切换的情况

VRC.Quest.Input.8：系统手势被保留，不应在应用中触发任何其他操作

如需了解如何实现手势追踪以及手势追踪在应用中的使用方式，请参阅 OC6 视频演示：手势追踪深入解读：技术、设计和体验⁠。

对于戳、拿取以及基于射线的选择等标准手部互动，推荐使用互动 SDK。下面的章节涵盖了用于自定义手势追踪实现的底层 Meta 核心 SDK API。如需了解更多信息，请参阅 Unreal 引擎中的手势追踪。

手势追踪架构

下图展示了 Unreal 引擎的手势追踪实现架构，同时说明手部输入信息如何沿用与控制器输入相同的机制进行数据传输。

Architecture diagram showing hand input routed through the Unreal Engine input system.

如图所示，设备输入仍是 Unreal 引擎输入数据的主要来源。设备输入会经由 Unreal 引擎输入系统传导手部输入数据，传导方式与控制器按钮和摇杆输入完全相同。捏拉和捏拉力度也会作为手部输入数据传导。

网格/骨架和骨骼旋转等手势特定功能通过 OculusXRInput 模块中的 UOculusXRInputFunctionLibrary 类提供。此 Blueprint 函数库提供了静态方法，用于访问手部特定数据，如手部缩放、手指尖姿势、骨骼旋转、追踪置信度等。

在项目中启用手势追踪

您可以在 Project Settings（项目设置）中开启 Unreal 引擎的手势追踪功能，此操作会为您项目的 Android 清单添加 com.oculus.permission.HAND_TRACKING 接入点。

前往 Edit（编辑）> Project Settings（项目设置），转至 Plugins（插件），然后选择 Meta XR。在 Hand Tracking Support（手势追踪支持）下，选择：

Controllers（控制器）：不会为您的应用启用手势追踪

Controllers and Hands（控制器和手势）：用户可以在应用中使用手势追踪或控制器

Hands Only（仅限手势）：用户必须在其设备上启用手势追踪，才能使用您的应用

高频手势追踪

如要设置高频率，在Project Settings（项目设置）> Plugins（插件）> Meta XR > Hand Tracking Frequency（手势追踪频率）中，选择 High（高）。

集成详情

Unreal 引擎的手势追踪集成包含以下组件。

输入模块更新

总的来说，输入模块可为手势追踪提供以下额外支持：

输入模块支持 Touch 控制器和手势追踪的输入。

输入模块通过 Unreal 引擎的输入事件系统传递捏拉和捏拉力度。

模块将更新并存储新的手势，可以通过 Blueprint 或 UOculusXRHandComponent 访问。

具体包括：

可通过 UOculusXRInputFunctionLibrary Blueprint 函数（例如 GetTrackingConfidence 和 IsHandTrackingEnabled）获取的手部状态数据，包括手势和追踪状态。

捏拉输入会通过按键事件与轴输入，更新捏拉状态和捏拉力度

Unreal 引擎输入系统已为手部定义全新的按键名称和轴输入，可识别单只手上的每根手指（拇指、食指、中指、无名指、小指）。

捏拉力度值可以绑定到 UE 输入设置，这样其事件就可以与 Blueprint 和 UOculusXRHandComponent 关联。详情请参阅输入绑定，了解如何操作。

更新手势

使用 GetControllerOrientationAndPosition 识别手部位置

使用获取手指尖姿势和骨骼旋转角度的自定义函数

手势追踪输入绑定

手势追踪通过 Unreal 引擎输入系统在 Oculus 手势类别下开放输入绑定。每根手指的 PinchStrength 值（例如 OculusHand_Left_IndexPinchStrength）可以绑定为轴映射，并返回表示捏拉力度的浮点值。

捏拉按钮事件（例如 OculusHand_Left_IndexPinch）在内部注册，但无法通过标准操作映射用户界面使用。如要响应捏拉按钮事件，请通过 C++ 轮询数值或使用 UOculusXRInputFunctionLibrary Blueprint 函数实现。

如要创建捏拉力度的轴映射：

前往 Edit（编辑）> Project Settings（项目设置），然后找到 Engine（引擎）> Input（输入）。

在 Axis Mappings（轴映射）下，添加新的映射。

对于映射键值，搜索 Oculus Hand（Oculus 手势）类别，查找可用的手势追踪输入绑定。下图展示了一个示例：

手势追踪 Blueprint

Unreal 引擎集成在 UOculusXRInputFunctionLibrary 上提供了多个 Blueprint 函数，用于获取手势追踪数据。

函数	描述
GetBoneName	根据骨骼编号返回骨骼名称
GetBoneRotation	返回所有与指定手型对应的骨骼旋转角度
GetDominantHand	返回哪只手是用户的惯用手
GetFingerTrackingConfidence	返回特定手指的追踪置信度
GetHandScale	返回手的大小
GetHandSkeletalMesh	返回指定手型的 `USkeletalMesh`
GetPointerPose	返回当前的手指尖姿势
GetTrackingConfidence	返回指定手部的追踪置信度
InitializeHandPhysics	在运行时手部网格初始化物理胶囊
IsHandInteractionProfile	如果当前互动配置为手部，则返回 true
IsHandPositionValid	如果手部位置数据有效，则返回 true
IsHandTrackingEnabled	如果设备上启用了手势追踪，则返回 true
IsPointerPoseValid	如果手指尖姿势有效，则返回 true
IsSimultaneousHandsAndControllersEnabled	如果启用了同时使用手和控制器模式，则返回 true
SetSimultaneousHandsAndControllersEnabled	启用或禁用同时使用手和控制器模式

手组件

UOculusXRHandComponent 是 OculusXRInput 模块的一部分。此组件是 Unreal UPoseableMeshComponent⁠ 的子类，必须作为 UMotionControllerComponent（负责为手部提供姿势追踪与延迟更新功能）的子组件。

此组件负责加载网格/骨架以及更新骨骼。组件还负责为手部设置新材质，在追踪丢失/置信度低时隐藏手部。该组件还提供了更新根姿势、更新根缩放、设置手指尖姿势根节点以及启用物理胶囊的选项。

下图展示了这些属性的示例，以及如何在 Unreal 引擎中设置这些属性。