Upgrading the plugin version

Minor Changes

The Ultraleap Unity plugin adheres to Semantic Versioning which means that you should be able to upgrade between minor versions without any breaking changes. E.g. going from version 6.11 -> 6.12 or 6.12.0 -> 6.12.1 will not cause any issues with pre-written code.

Feel free to upgrade to the latest and greatest!

Major Changes

Major version changes, such as going from version 5.x -> 6.x will come with some breaking changes. To upgrade your project between major version changes, please click the relevant drop down from the list below:

Upgrading Ultraleap Unity Plugin 6X to Ultraleap Unity Plugin 7X

Note

Ensure you have upgraded to Unity 2021 LTS or newer, Unity Plugin 7.0 does not support earlier versions as they are no longer supported by Unity

Note

Make sure to re-import any example samples to avoid errors. Be aware, doing so will replace any content in the example samples folders

Note

If using .unitypackages it is recommended to delete the existing plugin and samples before importing the new version to avoid old files remaining in your project. Or consider trying OpenUPM

  • Interaction engine has been deleted!

    • You will need to update your project to use physical hands. You can find out how to set up your scene here: Physical Hands

  • Namespace Changes:

    • The “Leap.Unity” namespaces have been changed to “Leap”. This will affect any script which uses Ultraleap features.

    • In order to upgrade, you will need to change all uses of the namespace “Leap.Unity” in your project to use “Leap” instead.

  • We Have Removed and or Replaced Multiple Detection Utilities. Most of these can and should be replaced using the pose detector:

    • Abstract Hold Detector

    • Detector Logic Gate

    • Extended Finger Detector

    • Finger Direction Detector

    • Palm Direction Detector

    • Proximity Detector

    • Pinch Detector has been moved to a new location “Packages/Tracking/Core/Runtime/Scripts/Utils/” and we have also added a new Grab Detector in the same location. You can find information on them here: Pinch Detector and Grab Detector.

  • Physical hands buttons have a whole new feel. you can check it out here: Buttons.

  • Physical Hands Buttons now support primary hover. This is an optional checkbox on the button script and means that only one button can be pressed at a time by each hand. Examples of this can be found in the Physical UI scene scene: Assets > Samples > Ultraleap Tracking > x.x.x > XR Examples > 2.Interactions > 2. Physical UI

  • New accessors for getting Fingers and bones from an Ultraleap.Hand. You must now use: “Hand.Finger, Hand.Bone and Finger.Bone”

example of how to get fingers and bones

  • Prefab create menu now uses Physical Hands prefabs instead of Interaction Engine prefabs

  • Shaders have been moved to a new “Ultraleap” folder and the default color property for all shaders have been renamed to use the standard “_Color” property name.

If you are using the included Ultraleap shaders and need access to the color parameter, you may need to update the accessor name.

  • Ultraleap Controller support has been removed in favour of using Unity XRI. You can find our documentation on controller support through XRI here and Unity’s documentation here.

If you were using Interaction Engine, we recommend that you convert your projects to Physical Hands and use the soft contact mode which provides the same great interactions in an easy to use way and can take advantage of all the great improvements in version 7 and later.

However, if you still need the Interaction Engine, we recommend using version 6.X although this version will no longer be receiving updates.

You can find information regarding changes in the Changelog, this will be updated with each new release.

If you find there is missing information in this document or would like assistance upgrading, please let us know via Github Discussions, our discord channel or our contact us form.

Upgrading Ultraleap Unity Plugin 5X to Ultraleap Unity Plugin 6X

Note

Ensure you have upgraded to Unity 2020 LTS or newer, Unity Plugin 6.0 does not support earlier versions as they are no longer supported by Unity

Note

Make sure to re-import any example samples to avoid errors. Be aware, doing so will replace any content in the example samples folders

Note

If using .unitypackages it is recommended to delete the existing plugin before importing the new version to avoid old files remaining in your project. Or consider trying OpenUPM

  • .ToVector(), .ToLeapQuaternion(), .ToVector3() and .ToQuaternion() can be removed as we no longer use our own version of Vector and Quaternion

  • Use of Vector and LeapQuaternion can be converted to use Unity’s Vector3 and Quaternion with relevant utilities e.g. Vector3.magnitude

  • MainCameraProvider.mainCamera can be replaced with Camera.main

  • Constructors for Arm Hand and Finger now use Vector3 and Quaternion as parameters rather than Vector and LeapQuaternion

  • GenericHand model has changed → If you are referencing any of its bones by name, you may need to reassign those references

  • Some Attributes, DataStructures and Utilities including Swizzle have moved to Leap.Unity namespace

  • If you were converting units from Leap units (mm) to Unity units (m), you may no longer need to. This is also true for changing coordinate space

example of changes required

A large collection of utilities that are no longer used directly in the Plugin have been moved to a Legacy Package. If something you use is missing, it is worth checking there and making your own copy of the code (as it is covered under the Apache v2 license, the license file should be included when copying.) These files have been updated to work with 6.0 but will not be maintained going forward.

  • ImageRetriever prefab and LeapEyeDislocator.cs (formerly used for passthrough) - Utility of which is replaced by ‘VR Infrared Camera’ prefab in the Tracking Examples package

  • Preview XR2

  • Foreground and ThresholdOverlay shaders and materials

  • Rigid Hands

  • Tweens, Animations and Splines

  • Geometry Utils

You can find information regarding changes in the Changelog, this will be updated with each new release.

If you find there is missing information in this document or would like assistance upgrading, please let us know via Github Discussions, our discord channel or our contact us form.

Upgrading Ultraleap Unity Modules 4X to Ultraleap Unity Plugin 5X

Follow this guide to upgrade to the new Ultraleap Hand Tracking Plugin for Unity from our Unity Modules.

The existing Unity Modules can be found at Assets/Plugins/LeapMotion. You will need to remove these assets from your project before upgrading to the Unity Plugin.

Quick Checks:

  • Make sure any unsaved changes you wish to keep are saved.

  • Make sure any assets for your project are not located in the Plugins Folder before pressing delete.

  • Ensure Unity is closed before pressing delete on the Plugins Folder.

Once the Modules are deleted you are able to re-open Unity, you will be faced with a wall of errors relating to missing scripts. You now need to install the new Unity Plugin.

You can now get our Unity Plugin via OpenUPM.

  • Ensure you have the Ultraleap Hand Tracking Software (V5.2+) installed

  • Remove any existing Ultraleap Unity modules from your project.

  • Setup only needs to be performed once per Unity project.

  • In Unity, select Edit -> Project Settings -> Package Manager, add a new scoped registry with the following details:

  • Name: Ultraleap

  • URL: https://package.openupm.com

  • Scope(s): com.ultraleap

scoped registry

  • Open the Package Manager (Window -> Package Manager) and navigate to “My Registries” in the dropdown at the top left of the window.

my registries

  • Ultraleap UPM packages should be available in the list. Click on the package you wish to modify.

package list

If you prefer you can still use .unitypackage files to get your Ultraleap Hand Tracking Plugin for Unity. This can be helpful if you need to modify the package content. You need to be comfortable that you will have to check back regularly to get updated versions.

  • Ensure that you have the Ultraleap Hand Tracking Software (V5.2+) installed.

  • Remove any existing Ultraleap Unity modules from your project.

  • Download Unity Package file

  • Right-click in the Assets window, go to Import Package and left-click Custom Package.

  • Find the Tracking.unitypackage and import it. This includes Core, Interaction Engine, and the Hands Module.

  • Experimental content can go through many changes before it is ready to be fully supported. At some point in the future, preview content might be promoted to the stable package, however it might also be deprecated instead. Because there is no guarantee for future support, we do not recommend using preview packages in production.

  • Our plugin content is added to Assets/ThirdParty/Ultraleap/Tracking from where you will see Core, Hands, Interaction Engine and Examples folders.

Other installation options are also available. See our Github repo for more information.

If you are using Unity 2020.4 (LTS) or newer with XR then you will need to follow the Unity documentation on how to configure your project.

Upgrade XR

If you are using any of the scriptable render pipelines (SRP) then you will need to follow the appropriate Unity documentation for upgrading shaders:

Upgrade URP Upgrade HDRP

If you are using Unity 2019.4 (LTS) and you get errors related to “SpatialTracking” upon importing, you will need to install the following package:

XR Legacy Input Helpers

If you are using Unity 2020.1 or newer and you get errors related to “SpatialTracking” upon importing, you will need to install the following package:

XR Plugin Management

You can find information regarding changes in the Changelog, this will be updated with each new release.

Internal testing suggests these are a few manual steps to update from the Modules to the Plugin:

Core

Leap Rig - This has been deleted as we no longer enforce a camera hierachy or a Hand Model Manager. To re-create this in your scene, you will need to use:

  • Service Provider (XR) - Make sure to include a reference to the camera

  • A hand model of your choosing -

Capsule hands can be found in the core folder All other hands can be found in the hands folder

LoPoly Rigged Hand Left LoPoly Rigged Hand Right These have been moved to the Hands Module Folder.

Interaction Engine

Scripts lose references to interaction manager - You will need to manually update the reference to the Interaction Manager if its missing in the inspector