UE5插件
1. 系统要求
UE 5.0~5.6版本
Windows 7 SP1 及以上版本
插件打包只支持Windows和Android
2. 开发准备与插件下载
请首先确保Udexreal HandDriver 软件已经成功存放到本地，如果还未进行此操作，请先存放。
下载HandDriver插件包到本地，插件包下载地址为（提取码: 7p56）：
2.1. 插件V1.3.2
请搭配HandDriver2.1.3之后（含）版本使用。
2.2. 插件V1.1.0之前（含）版本
如果您插件为V1.1.0之前（含）版本，而HandDriver为2.1.2之后（含）版本，请在HandDriver端数据串流中勾选“旧插件”。
HD2.1.3
HD2.1.2
HandDriver2.1.1之前（含）版本仅搭配v1.1.0之前（含）的UE插件。
2.3. 兼容性说明
如果您之前打包应用时所对应的HandDriver为2.0.5之前（含）版本（即不支持创建角色的HandDriver），而您又暂时不能升级UE插件，请您使用HandDriver2.1.2之后的版本，并在HandDriver端角色名称中使用格式为DeviceX_XXXX的角色名，例如Device1_5555。
2.4. UE5.5问题说明
UE5.5 在编辑模式下连接 livelink 手部不会动：
不影响插件功能正常使用；
放入新的蓝图（按照插件步骤创建好的蓝图或示例工程里的蓝图）测试或在运行模式下查看手模情况。
3. 快速开始
3.1. 运行 UDEXREAL HandDriver软件
在电脑上运行UDEXREAL HandDriver软件，确保手套正确连接并使用。软件使用方法参见HandDriver软件介绍
3.1.1. 数据发送设置
不同版本的HandDriver数据发送功能设置详见：
数据发送3.2. 在Unreal中新建工程
当你启动虚幻引擎（UE5）后，会自动显示虚幻项目浏览器。
选择最适合所在行业的开发类别。下面示例中选择了 游戏（Games）。
为项目选择模板。
在 项目设置（Project Defaults）页面，可选择质量/性能级别、目标平台、是否包含初学者内容等。
选择要存储项目的位置，并为项目命名。单击 创建项目（Create Project） 完成创建。
3.3. 安装插件
首先将 UE 插件 SDK文件夹整个复制到新建工程的Plugins文件夹下。如果新建工程目录下没有 Plugins 文件夹，新建Plugins文件夹即可。
然后打开工程，在编辑器窗口点击 Edit（编辑）->Plugins（插件） 打开插件管理窗口，搜索LiveLink插件，并保证其左侧为已勾选状态。（初次勾选LiveLink组件可能会需要重启UE软件，根据UE提示重启即可）
确保已勾选LiveLink插件后，再次在搜索框内搜索 HandDriver 插件，并保证其左侧为已勾选状态。
3.4. 手套LiveLink连接
确保手套与HandDriver软件为开启状态，且手套与HandDriver软件连接成功。
展开 窗口（Window） 选项卡并点击 虚拟制片-->实时链接（Live Link），启动 实时链接（Live Link） 工具。
打开之后，如果展开 源（Source） 窗口，将会看到 HandDriver 显示为新源。
展开 HandDriver 源（HandDriver Source） 选项，查看与其关联的IP和Port设置，格式为“IP:端口号”，其中端口号需与MoStreamHD中填写的端口号保持一致，默认IP地址0.0.0.0一般情况下无需修改，点击OK选项，此时下方会出现对应的设备Device1和Device2（如果只连接一副手套则只显示Device1）以及绿色小圆点，表示与MoStream HandDriver软件连接成功，如未出现绿色圆点，检查Port是否对应，或检查网络。
导入模型，注意要勾选骨骼网格体和导入网格体，并将SkeletalMesh模型拖入场景中。
选中SkeletalMesh模型，在细节（Detail）栏的Actor下先添加Hand组件，再添加组LiveLinkController，在主题表示（Role）中选择需要接收的设备（Device1或Device2）即可，如果只连接了一副手套，则仅显示Device1且只能选择Device1。
3.5. 测试Demo
我们在插件中准备了一个测试关卡，以便您在正式使用UDEXREAL手套到项目前测试效果。
打开已正确安装好插件的工程，在Plugins——Map中打开UdexrealTest关卡。
点击开始，运行关卡。
关卡中包含的模型为：UE官方VR手模型、MetaHuman女性身体标准骨骼模型。场景中模型所采用的手部数据调节参数，可作为参考在您的工程中使用。
橙蓝两组手模型相同，但使用的调节方法不同。橙色手使用的是调节Hand组件参数（参数已内置在插件内），蓝色手使用的是叠加动画（参考方法：MetaHuman手部骨骼调整方法）。可继续阅读文档学习两种手部效果调整方法，以选择更适合您的方法。
3.6. 使用插件实现全身动捕整合
全身模型要求：与全身动捕进行整合，第一步要将数据手套的手部骨骼定义与全身模型的手部骨骼定义相匹配，为了实现最佳效果，全身模型的手部骨骼及模型需要满足以下要求：
手腕关节及以下所有子关节骨骼轴向一致（即选中每个关节时，坐标系方向相同）。
模型手部所有骨骼局部旋转值归零后，手部模型的初始形态为四指并拢且伸直。
模型手部所有骨骼局部旋转值归零后，手指所有骨骼（不包含手腕关节，但包含拇指所有关节）的坐标系轴向需指向其子关节。
当数据手套和全身动捕系统一起联合使用时，我们提供了一个单独的动画蓝图节点来一键整合动捕系统数据和手套数据：选中SkeletalMesh骨骼网格体，右键创建动画蓝图
双击打开动画蓝图，在动画蓝图中分别导入全身动捕的节点（Livelink实时链接姿势）和数据手套的节点Udexreal Hand Pose，再导入一个Blend Hand Data In Mocap节点，分别将动捕的数据和手套的数据导入该节点，输出连接到输出姿势（OutputPose），最后点击编译即可。
出现如下图黄色警告为正常情况，不影响使用，忽略即可。
注意：对于有复杂动画蓝图的工程，如果您无法正确设置动画蓝图，建议先保持“Udexreal Hand Pose”-“Blend Hand Data In Mocap(Hand)”-“OutputPose(输出姿势)”的节点顺序放在动画蓝图节点最后，而将其他节点与“Blend Hand Data In Mocap(Mo Cap)”进行关联，此时如果能顺利驱动手部动作，再尝试根据您工程的实际情况调整动画蓝图。例如下图：
选中SkeletalMesh模型，将蓝图中的骨骼模型配置为动画蓝图驱动，在动画类选项中选择刚刚创建好的动画蓝图：
将数据手套定义的手部骨骼名称和全身模型的手部骨骼名称匹配（启动插件后，会自动进行匹配，如匹配不成功，请进行手动匹配）。添加Hand组件并选中Hand组件，将模型左右手的骨骼关节名称一一复制到Hand组件对应的配置框中，即可完成名称匹配。同理，参照上述方法，在UE中也可以通过蓝图类建立骨骼关节点匹配，并将人物模型放置到场景中（请在场景中使用串流，UE依版本环境不同在蓝图类中可能无法观察到运动）。
3.7. 坐标系校订：对模型手指关节的Pitch Axis(俯仰角)、Yaw Axis(偏航角)、Roll Axis(旋转角)进行校订。
建议先校订手指俯仰角，再校订偏航角和旋转角；
校订俯仰角时，可先打开模型的骨骼树状图，将坐标系改为对象坐标系，然后随意选择一根手指的关节，按住W键，确认其俯仰角所对应的坐标轴（偏航角与旋转角同理）。例如，手指关节向下翻转角度对应的轴向指向X轴的正方向，即手指关节的俯仰角X，在坐标系栏中选择对应轴：Pitch=X；五指向外张开的方向指向Y轴的负方向，则手指关节的偏航角为-Y，在坐标系栏中选择对应轴：Yaw=-Y；那么旋转角对应的则是Z轴，从手指关节的坐标系来看Z轴指向的是负方向，那么手指关节的旋转角为-Z，在坐标系栏中选择对应轴：Roll=-Z；
校订完成后，即可展示手部动作，如果关节方向旋转不正确，可反复校对直到取得正确的结果（偏航角与旋转角的数值通常不同，但在某些情况下需一致才能实现正确的效果，如下图）：
3.8. 大拇指参数调整
3.8.1. 拇指根节点系数 Thumb Coefficient
调节大拇指在实时串流时的向内弯曲系数（系数范围0-1），拇指根节点系数的值越低，向内弯曲程度越小；拇指根节点系数的值越高，向内弯曲程度越大。
3.8.2. 拇指根节点偏移(Thumb Pitch/Yaw/Roll Offset)
调节大拇指X、Y、Z轴在旋转时的偏差系数（本偏差实为角度，可将光标放入输入框内拖动，或直接填入角度数值观察效果），在实时串流时可以通过调整三轴的数值对大拇指的旋转方向进行调整，以达到最优效果（注意：想要看到调整后的效果，需在调整数值后松开鼠标方可观测到）。
3.8.3. 拇指根节点旋转坐标系(Thumb Pitch/Yaw/Roll Axis)
勾选Adjustment For Thumb Axis后启用，可以单独校订大拇指的Pitch、Yaw、Roll的旋转坐标系，不会影响其他四个手指的旋转坐标系。
3.9. 参数保存与复用
调整完参数后可以保存数据，方便数据迁移与复用。以下为使用方法参考视频。
点击Save Setting按钮。
选择一个Content下的文件夹保存。
在对应的文件夹下可以看见新保存的数据。
右键点击保存的数据，可导出为csv格式文件，以在不同版本的UE间复用。
从外部导入csv格式的数据时，注意要选择 HandDriverStructSetting 行类型。
在Hand组件中的 HandDriverSetting属性 里选择需要的数据表即可切换数据。
3.10. 重定向方法驱动手部模型
如果遇到手指骨骼轴向与我们标准模型不对应，或是不想调节参数的情况，可以使用重定向的方式。
手指骨骼轴向顺着手指朝向，正确
错误，建议修改骨骼轴向或重定向
在插件的测试Demo中找到f_med_nrw_body，这是metahuman的标准骨骼，我们已经针对于它完成了hand组件中的参数调节。可以直接以此为重定向驱动的源。
3.11. 针对VRM模型大拇指的调整
VRM模型的标准骨骼节点比较特殊，大拇指的骨骼轴没有顺着手指方向，仅凭调整大拇指轴向参数很难达到预期效果。
针对VRM的模型，可以开启Hand组件中的UseVrmModel选项，开启后会自动适配VRM模型的大拇指骨骼，不必再对大拇指进行单独调准。
3.12. 有关MetaHuman模型的参数处理（也适用于所有模型）
采用MetaHuman模型时，由于其默认初始状态为五指弯曲且张开，因此需要进行手指参数调整。其他模型如果也有类似情况，可以是尝试此参数调整。
在 HandDriverStructSetting 中选择 宇叠参数_MetaHuman 可以快速导入预设参数
Other (L/R) Fingers Yaw Offsets
Index：食指偏航调整；
Middle：中指偏航调整；
Ring：无名指偏航调整；
Pinky：小指偏航调整；
以上数值，建议可在手指伸直并拢时进行调整，即调整手指伸直并拢时的手指间距。参考经验值如上图所示（分别为-10，0，-12，-18），但请依据实际情况进行调整。
Overall Fingers Adjust - StraightenFinger
该选项为“拉直手指”，启用后会自动将弯曲手指拉直（仅针对于MetaHuman，其他模型不保证效果），请依据实际情况选择是否开启。
Overall Fingers Adjust - (L/R) Finger Pitch Offset
该参数作用于手指无法伸直的情况，即用户实际手指已伸直，但模型未伸直。该参数作用于四指的根关节和中间关节的俯仰。本插件已经针对MeteHuman模型开启“StraightenFinger”选项，通常情况下无需调整本参数。
Overall Fingers Adjust - (L/R) Finger Coefficient
该参数为“手指间距参数”，建议可在握拳时进行调整，即调整握拳时的手指间距。参考经验值为5，但请依据实际情况进行调整。
补充说明：以上参数调整可基本满足手指伸直并拢和握拳的状态，不过可能会因各人手型、标定准确度、手套匹配度等不同而表现一定差异。
MetaHuman手部参数的经验值（以左手为例）
经我们调整，得出了一组较为适合的MetaHuman手部的参数，可供参考。
3.13. 手套控制器（摇杆按键）的功能说明
HandDriver2.1.3开始可支持带有控制器（摇杆按键）的方形数据盒手套，但只有V1.3.0之后的插件版本才支持控制器接入。
3.14. 跨设备多人联机
当需要在一台电脑中运行两幅以上的手套时，可以在其他电脑上运行HandDriver软件把数据发送到当前设备。
其他电脑发送数据到当前设备没有被使用的端口号
在LiveLink中添加新的源，注意端口号填写正确
此时，在LiveLink中可以看见多台设备。
选择场景中的Actor，找到细节面板中的LiveLinkComponentController组件，在SubjectRepersentation的下拉面板中选择想要驱动此Actor的设备。
3.15. 退出UE时关闭源（source）
当完成操作需要退出UE时，请按以下步骤操作关闭HandDriver插件：
展开 窗口（Window） 选项卡并点击 实时链接（Live Link），启动 实时链接（Live Link） 工具。
打开之后，点击HandDriver LiveLinklocalhost 后的删除图标，将HandDriver LiveLink删除即可。
3.16. 针对打包后LiveLink源无法保存的情况
每次重启软件后，会出现LiveLink“源”被清空，需要重新添加“源”人物才能动的情况。解决这种情况的问题，请按以下步骤操作（本方案为参考方案，若有问题敬请反馈）：
3.16.1. 方案一：按照步骤自己添加
确保需要手部动捕的Actor的 LiveLinkComponentController 组件 中的SubjectRepresentation已选中了手套的 Device1 （显示为None的话，需先操作上文步骤中的手套LiveLink连接）
打开需要手部动捕的Actor的 蓝图，在 事件开始运行（Event BeginPlay）后依次添加节点“延迟（Delay）---Create HandDriver LiveLink Source at Runtime”
右键点击 Create HandDriver LiveLink Source at Runtime 的返回值 Handle 提升为变量，修改变量命名为 HandDriverSource ，并连接。
在 Create HandDriver LiveLink Source at Runtime 的变量 ConnectString中输入 0.0.0.0:5555。
在 事件结束运行（Event End Play）后添加节点 “RemoveSource” ，把 HandDriverSource 作为参数连入。
编译保存，此时 实时链接（Live Link）列表中没有HandDriver源也可驱动Actor手部动捕。
3.16.2. 方案二：使用插件预置的对象
把插件预置的蓝图对象（BP_UdexLiveLinkSource/BP_UdxLiveLinkSource）放入场景里，建议每个场景只放置一个
3.17. 在头显中使用UDEXREAL Glove Service时添加 LiveLink 数据源
点击这里查看：VR头显安卓服务Glove Service用户手册。通过Copy下面的代码，在ue里直接Paste即可，或者使用示例Pawn里方法，win平台使用时，修改WinRole变量的信息，Andriod平台时使用示例默认值。
4. 常见问题
4.1. 在UE已经串联的情况下，在HandDriver 2.1.0 里修改角色名后，会导致UE重新识别出一个新的源，而之前连接的源默认为断开
答：出现此情况原因是之前连接的过程中已经产生了缓存，由于识别是以角色名为准，所以就产生了新的源，解决方式：把之前绑定老的角色名修改成新的角色名就可以重新使用了
4.2. 在角色数据源处修改最新的源，角色不能被实时驱动（如果发现根据流程走但是模型不会动请重置当前人物）
答：选中UE场景里需要切换的源的角色，点击切换源后面的图标重置源接口，再重新进行本手册第三章第四节手套LiveLink连接操作的第 f 步骤把最新的源给到该角色即可。
Last updated