From ab312297dad7ec058d233053a390c6089fa59d1e Mon Sep 17 00:00:00 2001 From: Mamadou Babaei Date: Fri, 16 Aug 2024 12:30:28 +0200 Subject: [PATCH] add topic: Upgrade Guide --- Handbook/src/SUMMARY.md | 2 +- Handbook/src/misc/upgrade-guide/README.md | 52 +++++++++++++++++++++++ Handbook/src/overview/README.md | 2 +- 3 files changed, 54 insertions(+), 2 deletions(-) create mode 100644 Handbook/src/misc/upgrade-guide/README.md diff --git a/Handbook/src/SUMMARY.md b/Handbook/src/SUMMARY.md index d70d8b80..cca2460a 100644 --- a/Handbook/src/SUMMARY.md +++ b/Handbook/src/SUMMARY.md @@ -56,7 +56,7 @@ Welcom to the SenseGlove Unreal Engine Handbook! - [SenseGlove Console Commands](misc/console-commands/README.md) - [Deploying to Android (Standalone)](misc/android-standalone-deployment/README.md) -- [Upgrade Guide]() +- [Upgrade Guide](misc/upgrade-guide/README.md) - [Optimizing for Higher FPS](misc/optimize-higher-fps/README.md) # 🛠️ Advanced Topics diff --git a/Handbook/src/misc/upgrade-guide/README.md b/Handbook/src/misc/upgrade-guide/README.md new file mode 100644 index 00000000..9d9e7d51 --- /dev/null +++ b/Handbook/src/misc/upgrade-guide/README.md @@ -0,0 +1,52 @@ +# Upgrade Guide + +The transition from `v2.0.x` to `v2.1.x` introduces [numerous changes](../../appendix/changelog.md), 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](https://dev.azure.com/SenseGlove/_git/SenseGlove-Unreal-SGBasicDemo), the upgrade process is quite straightforward. We successfully upgraded SGBasicDemo to [SGBasicDemo-OpenXR](https://dev.azure.com/SenseGlove/_git/SenseGlove-Unreal-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](../../appendix/changelog.md) 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](https://youtu.be/VbWfoep-Hsg) is available. +>
+> +>
+ +1. Remove the existing `Plugins/SenseGlove` folder from your project. + +2. [Obtain the latest `v2.1.x` version of the plugin](../../getting-started/installation/) either from [the Epic Games Launcher](../../getting-started/installation/epic-games-launcher.md) or [Microsoft Azure DevOps Repositories](../../getting-started/installation/microsoft-azure-devops-repositories.md) 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](../../getting-started/setup-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](../../getting-started/setup-virtual-hand-meshes/#setting-up-the-senseglove-grab-and-touch-sockets). + +7. Set up the [SGPawn](../../getting-started/setup-senseglove-default-classes/sgpawn.md) to use the new virtual hand meshes for the `HandLeft`, `HandRight`, `RealHandLeft`, and `RealHandRight` components. + +8. Adjust the [Virtual Hand Mesh Settings](../../plugin-configuration/plugin-settings/virtual-hand/mesh.md) and ensure the `Left Hand Reference Mesh` and `Right Hand Reference Mesh` are set correctly. + +9. Check and adjust the [Virtual Hand Animation Settings](../../plugin-configuration/plugin-settings/virtual-hand/animation.md) as needed. + +10. You might also want to [set up the Wrist Tracking Hardware](../../getting-started/setup-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`](../../getting-started/setup-senseglove-default-classes/sggameinstance.md) and [`SGGameUserSettings`](../../getting-started/setup-senseglove-default-classes/sggameusersettings.md) if you want to use the new [SenseGlove console commands](../../misc/console-commands/) or take advantage of the [Engine Scalability Settings to achieve higher framerates in your project](../../misc/optimize-higher-fps/). + +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](../../plugin-configuration/plugin-settings/tracking/glove-tracking.md) 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. diff --git a/Handbook/src/overview/README.md b/Handbook/src/overview/README.md index 79e19cb2..09ebdb8b 100644 --- a/Handbook/src/overview/README.md +++ b/Handbook/src/overview/README.md @@ -56,7 +56,7 @@ Toipcs that do not fall under any specific category: - [SenseGlove Console Commands](../misc/console-commands/) - [Deploying to Android (Standalone)](../misc/android-standalone-deployment/) -- [Upgrade Guide]() +- [Upgrade Guide](../misc/upgrade-guide/) - [Optimizing for More FPS](../misc/optimize-more-fps/) ## 🛠️ Advanced Topics