> For the complete documentation index, see [llms.txt](https://udexreal.gitbook.io/udexreal-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://udexreal.gitbook.io/udexreal-docs/plugins/ue5-plugin-tutorial.md). # UE5 Plugin Tutorial This manual is intended for technical personnel who use UDEXREAL data gloves to develop UE5 projects. First-time users are advised to complete environment preparation, plug-in installation, Live Link connection, and example level verification in chapter order before proceeding to model parameter adjustment and advanced deployment. ## 1. Preparation Before Use * Unreal Engine: UE5.0–5.7 * Target platforms: Supports Windows and Android packaging ### 1.1. Software and Plugin Preparation * Before configuring your UE project, install and launch UDEXREAL HandDriver on your local machine first. * Download HandDriver UE plugin package {% embed url="" %} ### 1.2. Version Compatibility Requirements Please use with HandDriver version 2.1.3 or later. ## 2. Plugin Installation and Quick Verification ### 2.1. Launch UDEXREAL HandDriver Launch UDEXREAL HandDriver on your computer, and confirm that the data gloves are properly connected and can continuously output data. For instructions on installing and calibrating HandDriver and connecting the gloves, please refer to {% content-ref url="/pages/mZXVKTqkEhpFIznRkpoQ" %} [Software Instruction](/udexreal-docs/software-instruction/software-instruction.md) {% endcontent-ref %} #### 2.1.1. Data Transmission Setting Enable data sending in HandDriver and record the sending port. The UE Live Link data source must use the same port. For detailed settings, refer to {% content-ref url="/pages/EhMJSyJ4h6Z0bj8mUAwR" %} [Data Transmission](/udexreal-docs/software-instruction/software-instruction/data-transmission.md) {% endcontent-ref %} ### 2.2. Install and Enable the Plugin {% stepper %} {% step %} Create a Plugins folder in the root directory of the UE project (skip this step if it already exists). {% endstep %} {% step %} Copy the entire HandDriver plugin into "\/Plugins". You can also install it to the UE engine plugin directory, but project-level installation makes version isolation easier (choose either option).

{% endstep %} {% step %} Reopen the project. If UE prompts you to compile modules, complete the compilation according to your project environment. {% endstep %} {% step %} Select "Edit → Plugins", search for HandDriver, and confirm that the plugin is enabled. Restart the editor as prompted.

{% endstep %} {% endstepper %} ### 2.3. Establish a LiveLink Connection **Pre-check**: The data gloves are powered on, HandDriver is running, and the connection status in HandDriver is normal. In the UE editor, select "Window → Virtual Production → Live Link" to open the Live Link panel.

In the Live Link panel, expand "Source" and confirm that a HandDriver source can be added.

{% stepper %} {% step %} Add a HandDriver Source, and enter "IP:Port" in the connection string. {% endstep %} {% step %} The port must match HandDriver's sending port; the default listening address 0.0.0.0 usually does not need to be modified. {% endstep %} {% step %} Click OK. After a successful connection, Device1/Device2 will be displayed; if only one glove is connected, only Device1 will be displayed. {% endstep %} {% step %} Confirm that a green status dot appears next to the device. If it does not turn green, check for port conflicts, firewall settings, sender status, and network connectivity.

{% endstep %} {% step %} Select the Skeletal Mesh Actor to be driven, and add a Hand component in the "Details" panel. {% endstep %} {% step %} Continue by adding a LiveLinkComponentController component. {% endstep %} {% step %} In Subject Representation, select the data source to receive (e.g., p or teleop). If only one glove is connected and the role name is teleop, select teleop.

{% endstep %} {% endstepper %} ### 2.4. Verify with the Example Level The plugin provides an example level. It is recommended to complete the example verification first before integrating it into a formal project. In the Content Browser, open HandDriverContent/Map/Map\_UdxRealTest. {% columns %} {% column width="66.66666666666666%" %}

{% endcolumn %} {% column width="33.33333333333334%" %}

{% endcolumn %} {% endcolumns %} * The example level includes multiple preset models and their hand parameters, which can serve as a baseline for project configuration. * Select the preset closest to your target model and fine-tune it based on the actual skeleton and hand shape. * Run the level to confirm that finger bending, spreading, thumb rotation, and left/right hand mapping all work correctly. ## 3. Model Adaptation and Parameter Calibration ### 3.1. Model and Skeleton Requirements Before integrating full-body motion capture, first confirm that the data gloves and the target model have consistent hand bone definitions. The target model should meet the following requirements: * The bone axes of the wrist joint and all its child joints are consistent (i.e., the coordinate system orientation is the same when each joint is selected). * After all bone local rotation values of the model's hand are set to zero, the initial pose of the hand model is four fingers together and straight. * After all bone local rotation values of the model's hand are set to zero, the coordinate system axes of all finger bones (excluding the wrist joint but including all thumb joints) must point toward their child joints. {% stepper %} {% step %} Open the character animation blueprint, and add the full-body motion capture node "Live Link Pose" in the AnimGraph. {% endstep %} {% step %} Add the glove node "Udexreal Hand Pose". {% endstep %} {% step %} Add "Blend Hand Data In Mocap", connect the full-body motion capture data to Mo Cap, and connect the glove data to Hand. {% endstep %} {% step %} Connect the output of Blend Hand Data In Mocap to Output Pose.

Note: For projects with complex animation blueprints, if you cannot configure the animation blueprint correctly, it is recommended to first keep the node sequence "Udexreal Hand Pose" → "Blend Hand Data In Mocap (Hand)" → "Output Pose" at the end of the animation blueprint node chain, and connect the other nodes to the "Mo Cap" input of "Blend Hand Data In Mocap". If the hand movements can be driven successfully in this setup, then try adjusting the animation blueprint according to your project's actual situation. See the figure below for an example:

{% endstep %} {% step %} After launching the plugin, first check the automatic bone matching result. {% endstep %} {% step %} If automatic matching fails, select the Hand component and fill in the model's left and right hand bone names item by item into the corresponding configuration fields. {% endstep %} {% step %} You can also set up bone node mappings in the Blueprint class and place an instance of the character into the scene. {% endstep %} {% step %} Please verify the motion while the scene is running or in streaming state; depending on the UE version and environment, real-time motion may not be observable in the Blueprint preview. {% endstep %} {% endstepper %} {% columns %} {% column %}

{% endcolumn %} {% column %}

{% endcolumn %} {% endcolumns %} ### 3.2. Calibrate Finger Rotation Axes * It is recommended to calibrate in the order Pitch → Yaw → Roll. 1. Open the model's skeleton tree and switch the transform coordinate system to the object coordinate system. 2. Select any finger joint, press W to display the translation axes, and observe the axis and positive/negative direction corresponding to downward bending of the joint. 3. Set that axis as Pitch. For example, if downward bending corresponds to +X, set Pitch=X. 4. Observe the axis corresponding to the outward spreading of the five fingers and set it as Yaw. For example, if it corresponds to -Y, set Yaw=-Y. 5. Set the remaining rotation axis as Roll. For example, if it corresponds to -Z, set Roll=-Z.

After calibration is complete, the hand motions can be displayed. If the joint rotation directions are incorrect, repeat the calibration until the correct result is achieved (the Yaw and Roll values are usually different, but in some cases they must be identical to achieve the correct effect, as shown in the figure below):

#### 3.2.1. Reference video **Note:** The XYZ axis in this video is represented by the following numbers (-X=-3, -Y=-2, -Z=-1, X=0, Y=1, Z=2), and its principle is the same as the above. {% embed url="" %} ### 3.3. Thumb Parameter Adjustment:

#### 3.3.1. The Thumb Coefficient: Adjust the inward bending coefficient of the thumb during real-time streaming (coefficient range 0-1) , the lower the value of the thumb root node coefficient, the smaller the degree of inward bending; the higher the value of the thumb root node coefficient, the greater the degree of inward bending. #### 3.3.2. Thumb Pitch/Yaw/Roll Offset: Adjust the deviation coefficient of the X, Y, and Z axes of the thumb during rotation (This deviation is actually an angle, you can drag the cursor into the input box, or directly fill in the angle value to observe the effect), During real-time streaming, you can adjust the rotation direction of the thumb by adjusting the values of the three axes to achieve the optimal effect (Note: To see the adjusted effect, you need to release the mouse after adjusting the value). #### 3.3.3. Thumb Pitch/Yaw/Roll Axis:

After selecting Adjustment for Thumb Axis, the rotation coordinate system of the thumb Pitch, Yaw, and Roll can be individually calibrated without affecting the rotation coordinate system of other four fingers. #### 3.3.4. Thumb Performance Adjustment When MetaHuman Hands Are Brought Together

Parameter	Description
Is Enable	Enable this feature
Thumb 01 Pitch	Adjust the pitch angle of the first thumb joint in this state
Thumb 01 Yaw	Adjust the yaw angle of the first thumb joint in this state
Thumb 02 Pitch	Adjust the pitch angle of the second thumb joint in this state
Thumb 03 Pitch	Adjust the pitch angle of the third thumb joint in this state

### 3.4. Parameter Saving and Reuse After adjusting the parameters, the data can be saved, which is convenient for data migration and reuse. The following is a reference video of how to use it. {% file src="/files/ScGj5WsMj7U7AjjDYTzP" %} #### 3.4.1. Data Saving 1. Click Save Setting. 2. Select a save folder under the Content directory. 3. Confirm that new parameter data has been generated in the target folder. 4. If you need to reuse it across UE versions, right-click the data and export it as CSV.

#### 3.4.2. Importing and Using Data When importing a CSV from an external source, set the Row Type to HandDriverStructSetting.

Select the target DataTable in the HandDriverSetting property of the Hand component to switch parameters.

### 3.5. Using IK Retargeting to Drive the Hand Model When the finger bone axes of the target model are inconsistent with the plugin's standard model, or when it is not suitable to adjust parameters item by item, IK retargeting can be used. {% columns %} {% column width="50%" %}

Finger bones are oriented along the finger axis, CORRECT {% endcolumn %} {% column width="50.00000000000002%" %}

Finger bones are NOT oriented along the finger axis, WRONG. Please modify bone axis or retargeting {% endcolumn %} {% endcolumns %} 1. Find the **f\_med\_nrw\_body** in the test demo of the plugin, which is the standard skeleton of metahuman, and we have completed the parameter adjustment in the hand component for it. You can directly use this as the source of retargeting driver.

2. You can refer to the official documentation for creating and using Ik binding: [IK Rig Retargeting ](https://dev.epicgames.com/documentation/en-us/unreal-engine/ik-rig-animation-retargeting-in-unreal-engine?application_version=5.3)and [runtime IK Retargeting ](https://dev.epicgames.com/documentation/en-us/unreal-engine/runtime-ik-retargeting-in-unreal-engine?application_version=5.3). It should be noted that the fingers of the source model are not in a straight state. When adjusting the retargeting device, pay attention to adjusting the curvature of the finger joints to achieve the target effect

### 3.6. Adapting to VRM Models The thumb bone axes of VRM models usually do not point along the finger direction, and adjusting only the thumb axis parameters may not achieve stable results.

For VRM models, enable UseVrmModel in the Hand component. Once enabled, the plugin will automatically adapt to the VRM thumb bones, so there is generally no need to calibrate the thumb axes separately.

### 3.7. Adjusting MetaHuman Parameters The default hand pose of MetaHuman has all five fingers bent and spread, so additional finger parameter adjustments are required. Other models with a similar initial hand pose can also refer to this section. Select "UdxValue\_MetaHumanMesh" in HandDriverStructSetting to quickly fill in the preset parameters.

#### **3.7.1. Four-Finger Yaw Offset** * Index: index finger yaw adjustment; * Middle: middle finger yaw adjustment; * Ring: ring finger yaw adjustment; * Pinky: pinky yaw adjustment; The above values can be adjusted when the fingers are straight and close, that is, the distance between the fingers when the fingers are straight and close. The reference experience values are shown in the above figure (-10, 0, -12, -18), but please adjust according to the actual situation. #### **3.7.2. Straighten Finger** This option is "Straighten Finger". When enabled, it will automatically straighten the bent finger (only for MetaHuman, the effect is not guaranteed for other models). Please choose whether to enable it according to the actual situation. #### **3.7.3. Four-Finger Pitch Offset** This parameter applies to the situation where the finger cannot be straightened, that is, the user's actual finger is straightened, but the model is not straightened. This parameter applies to the pitch of the root joint and the middle joint of the four fingers. This plugin has enabled the "StraightenFinger" option for the MeteHuman model. **Usually, there is no need to adjust this parameter**. #### **3.7.4. Finger Spacing Coefficient** This parameter is "finger spacing parameter". It is recommended to adjust it when making a fist. The reference experience value is 5, but please adjust it according to the actual situation.

**Note**: The above parameter adjustments can basically satisfy the states of fingers straight and together and making a fist, but there may be certain differences due to variations in individual hand shapes, calibration accuracy, glove fit, etc. #### **3.7.5.** Empirical Values for MetaHuman Hand Parameters The following empirical values are applicable to common MetaHuman hands and can be used as initial values; please refer to the actual performance of the target model. {% columns %} {% column %}

{% endcolumn %} {% column %}

{% endcolumn %} {% endcolumns %} ## 4. Advanced Features and Deployment ### 4.1. Functional Description of the Glove Controller (Joystick Buttons) Starting from V2.1.3, HandDriver supports the glove with controllers (joystick and buttons), **ONLY the plugin after V1.3.0 supports the controllers.** {% content-ref url="/pages/HPeSDK0LHsLz83PVqucZ" %} [UE5 Plugin Tutorial of Controllers (For V1.3.1 and Above)](/udexreal-docs/plugins/ue5-plugin-tutorial/ue5-plugin-tutorial-of-controllers-for-v1.3.1-and-above.md) {% endcontent-ref %} ### 4.2. Cross-Device Multiplayer When more than two gloves need to be run on one computer, you can run the HandDriver software on other computers to send data to the current device.

1. Other computers send data to an unused port number (e.g., 7777) on the current device. 2. Add a new source in LiveLink, make sure the port number is filled correctly.

3. At this moment, multiple devices can be seen in LiveLink. 4. Confirm that each data source uses a unique port.

5. Confirm that Subjects from multiple devices are visible in Live Link, and that their status dots are green.

6. Select the Actor in the scene, and in the Subject Representation drop-down list of the LiveLinkComponentController, select the device used to drive that Actor.

### 4.3. Creating a Live Link Source at Runtime In some packaged projects, the Live Link "Source" list is cleared after a restart, causing the character to stop receiving glove data. You can create a data source at runtime, or use the plugin's preset Blueprint. Please choose either of the following solutions according to your project structure:

#### 4.3.1. Solution 1: Create a Data Source in the Character Blueprint 1. Ensure that the SubjectRepresentation in the **LiveLinkComponentController** component of the Actor that needs hand motion capture has the glove's **teleop** selected (if it shows None, you need to first perform the glove LiveLink connection described in the previous steps).

2. Open the target Actor Blueprint, and after Event BeginPlay, add a Delay node and a Create HandDriver LiveLink Source at Runtime node in sequence. 3. Promote the return value Handle of Create HandDriver LiveLink Source at Runtime to a variable, name it HandDriverSource, and complete the connections. 4. Fill in 0.0.0.0:5555 in ConnectString; the port must match HandDriver's sending port.

5. After Event End Play, add a Remove Source node and pass the HandDriverSource variable as a parameter.

6. Compile and save the Blueprint. Even if the Live Link list does not have the HandDriver Source saved in advance, the data source can still be created at runtime and drive the character. #### 4.3.2. Solution 2: Use the Plugin's Preset Object Place the plugin's preset Blueprint object (BP\_UdexLiveLinkSource/BP\_UdxLiveLinkSource) \[this object uses port 5555] into the scene. It is recommended to place only one per scene.

### 4.4. Adding a LiveLink Data Source When Using UDEXREAL Glove Service in a Headset Click 👉 to view: {% content-ref url="/pages/8ugjFTkBaDOXQZTPDv3d" %} [VR Headset Android Glove Service Manual](/udexreal-docs/gloves-in-vr-headsets/vr-headset-android-glove-service-manual.md) {% endcontent-ref %} You can copy the configuration below and paste it directly into UE, or refer to the example Pawn. On Windows, WinRole needs to be modified; on Android, the example default values can be used. {% code overflow="wrap" %} ```cpp (Subject= (Name="AndroidService"),Role=/Script/CoreUObject.Class'"/Script/LiveLinkInterface.LiveLinkAnimationRole"') ``` {% endcode %}

## 5. FAQ ### 5.1. A New Live Link Source Appears After Modifying the Role Name **Cause:** * Live Link caches connected role names; after the role name changes, it is recognized as a new data source. **Solution:** * Update the Subject/role name originally bound to the character to the new role name. ### 5.2. The Character Cannot Be Driven After Switching to a New Data Source **Solution:** Select the target character in the scene, and click the reset icon next to the data source selection item; then re-establish the Live Link connection according to Section 2.3, and select the latest data source for the character.

### **5.3.** Only Some Characters Can Be Driven After Packaging Solution: * Check whether the Hand component, bone mapping, and Live Link Subject of the character that cannot be driven are configured correctly. * Check whether the character's calibration status is updated synchronously with the sending end. ### 5.4. Hand Does Not Move in UE 5.5 Edit Mode **Solution:** * This phenomenon does not affect the normal use of the plugin in play mode. * Use a new Blueprint configured according to this manual or the example project Blueprint for testing, and check the model's hand movements in play mode.