Upgrade Guide

Upgrading from v2.7.x to v2.8.x

Summary of Breaking Changes

Starting with SenseGlove Unreal Engine Plugin v2.8.x, support for FXRMotionControllerData has been removed.

Although:

• Unreal Engine 5.5 and 5.6 still support the deprecated FXRMotionControllerData, and
• These engine versions are still supported by plugin v2.8.x,

the plugin now fully transitions to FXRHandTrackingState, which is the modern and recommended API introduced in Unreal Engine 5.5+ for OpenXR hand tracking.

Additionally:

• Plugin v2.8.x no longer supports Unreal Engine 5.4.
• Because FXRHandTrackingState is the forward-compatible OpenXR API, continued support for FXRMotionControllerData is no longer maintained in the plugin.

We have supported FXRHandTrackingState since v2.2.0 (released 2024-10-22), and it has been stable in production for several releases.

Who Is Affected?

This change only affects you if:

• You maintain a custom hand manipulation or tracking system, and
• Your implementation directly consumes FXRMotionControllerData provided by the SenseGlove plugin.

If you rely solely on the plugin’s provided components and standard integration workflow, no action is required.

Required Migration

If you are directly consuming FXRMotionControllerData, for your project to build or function as expected, you must migrate to:

FXRHandTrackingState

The migration is straightforward because both structures represent similar hand tracking data concepts within Unreal’s OpenXR framework.

A step-by-step explanation of how to work with FXRHandTrackingState is available in this third-party tutorial:

👉 Introduction to Virtual Reality, OpenXR Hand Tracking, and Gesture Detection in Unreal Engine

Why This Change?

• FXRMotionControllerData is deprecated.
• FXRHandTrackingState is the future-proof OpenXR hand tracking API.
• The existing Unreal Engine’s OpenXR implementation is centered around FXRHandTrackingState and FXRMotionControllerData has been completely removed form UE 5.7+.
• Removing legacy support simplifies the plugin architecture and aligns it with Unreal’s forward direction.

If you are already using FXRHandTrackingState or not directly consuming the OpenXR data, no changes are required when upgrading to v2.8.x.

Upgrading from v2.0.x to v2.1.x

The transition from v2.0.x to v2.1.x introduces numerous changes, including several breaking changes. The effort required to upgrade your project will vary depending on its complexity and which features of the SenseGlove Unreal Engine Project you are using. However, if you are working with a simple Blueprint project like SGBasicDemo, the upgrade process is quite straightforward. We successfully upgraded SGBasicDemo to SGBasicDemo-OpenXR by following the procedure outlined below.

These are the notable changes that might affect your project:

• The SenseGlove Virtual Hand and Wrist Tracker components no longer rely on the SenseGlove Hand Pose data from the underlying SenseGlove API. Instead, they use FXRMotionControllerData.
• The virtual hand animation system has been revamped to use FXRMotionControllerData and no longer relies on SenseGlove Hand Angles. This means the virtual hand meshes are animated using world space transforms instead of parent bone space transforms.
• The Allbreaker virtual hand meshes have been removed and are no longer supported as they are incompatible with the new OpenXR tracking and animation system.

Caution

Please consult the changelog before upgrading your project to see if any change affects or breaks your current project.

Note

For upgrading older versions of the plugin to v2.0.0, a YouTube tutorial is available.

1. Remove the existing Plugins/SenseGlove folder from your project.

2. Obtain the latest v2.1.x version of the plugin either from the Epic Games Launcher or Microsoft Azure DevOps Repositories and place it in the Plugins/SenseGlove folder that you've just removed.

3. It might be best to clean up and remove the following folders from your project before generating the project files or attempting to open your project with the Unreal Editor. This might prevent a certain class of build issues:

- Binaries
- Intermediate
- Saved

4. Build your project using your favorite IDE if it's a C++ project, or open your project's .uproject file with the Unreal Editor and wait for the Editor to build the necessary binaries and open the project.

5. Remove the Allbreaker virtual hand meshes if you are using them, as they are no longer compatible with the new animation system.

6. Import and set up a set of compatible virtual hand meshes such as the VRTemplate virtual hand meshes, and configure the materials, rigid bodies, and the SenseGlove Grab and Touch Sockets using the SenseGlove Sockets Editor.

7. Set up the SGPawn to use the new virtual hand meshes for the HandLeft, HandRight, RealHandLeft, and RealHandRight components.

8. Adjust the Virtual Hand Mesh Settings and ensure the Left Hand Reference Mesh and Right Hand Reference Mesh are set correctly.

9. Check and adjust the Virtual Hand Animation Settings as needed.

10. You might also want to set up the Wrist Tracking Hardware to use the new experimental HMD auto-detection feature. This allows the plugin to automatically configure the wrist tracking hardware at runtime, rather than limiting your builds to a specific HMD.

11. Set up the SGGameInstance and SGGameUserSettings if you want to use the new SenseGlove console commands or take advantage of the Engine Scalability Settings to achieve higher framerates in your project.

12. Additionally, the latest release introduces the ability to use hand-tracking as an alternative to SenseGlove hardware—albeit without haptic feedback—for rapid development and testing. It's also recommended to enable the Fallback to HandTracking if No Glove Detected feature to seamlessly switch to hand-tracking when a glove isn't connected.

13. If all steps have been followed correctly, your project should now be fully compatible with the new plugin release.