You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+4-5Lines changed: 4 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -48,10 +48,9 @@ MRTK3 requires Unity 2021.3.21 or higher. In addition, you need the [Mixed Reali
48
48
49
49
In previous versions of MRTK (HoloToolkit and MRTK v2), all packages were released as a complete set, marked with the same version number (ex: 2.8.0). Starting with MRTK3 GA, each package will be individually versioned, following the [Semantic Versioning 2.0.0 specification](https://semver.org/spec/v2.0.0.html). (As a result, the '3' in MRTK3 is not a version number!)
50
50
51
-
52
51
Individual versioning will enable faster servicing while providing improved developer understanding of the magnitude of changes and reducing the number of packages needing to be updated to acquire the desired fix(es).
53
52
54
-
For example, if a non-breaking new feature is added to the UX core package, which contains the logic for user interface behavior the minor version number will increase (from 3.0.x to 3.1.0). Since the change is non-breaking, the UX components package, which depends upon UX core, is not required to be updated.
53
+
For example, if a non-breaking new feature is added to the UX core package, which contains the logic for user interface behavior the minor version number will increase (from 3.0.x to 3.1.0). Since the change is non-breaking, the UX components package, which depends upon UX core, is not required to be updated.
55
54
56
55
As a result of this change, there is not a unified MRTK3 product version.
57
56
@@ -89,19 +88,19 @@ MRTK3 has been upgraded to use [Unity's XR Interaction Toolkit 3+](https://docs.
89
88
* The new controllers and rig retake the original names of the obsolete controllers.
90
89
* New controllers structure have been modified so that all of them have the same structure.
91
90
* The deprecated XRI2 XRController component has been removed from the controllers and its input actions have been moved to their interactors.
92
-
* The new controllers now have a Tracked Pose Driver components that holds references to the device's position, rotation, and tracking state input actions.
91
+
* The new controllers now have a Tracked Pose Driver components that holds references to the device's position, rotation, and tracking state input actions.
93
92
* Interactors now have a Tracked Pose Driver field that holds a reference to the Tracked Pose Driver component of the parent controller.
94
93
* Interactors now have a Mode Managed Root that holds a reference to the parent controller GameObject.
95
94
* Added new unity-tests for the new XRI3 functionality + components.
96
95
* Updated several unity-tests.
97
96
* Updated several scripts so that they work with both obsolete XRI2 and new XRI3 prefabs.
98
97
* Updated all scenes to use the new XRI3 rig + controllers.
99
-
* Made a copy of the old HandInteractionExamples scene and renamed as ObsoleteHandInteractionExample, this scene still consumes the old rig + controllers.
98
+
* Made a copy of the old HandInteractionExamples scene and renamed as ObsoleteHandInteractionExample, this scene still consumes the old rig + controllers.
100
99
101
100
A more detailed explanation of the changes can be found in [XRI2TOXRI3MIGRATIONGUIDE.md](./XRI2TOXRI3MIGRATIONGUIDE.md). The guide can also help others as a path for migrating their own solutions or MRTK3 forks from XRI2 to XRI3.
102
101
103
102
## Governance
104
103
105
104
For information on how the Mixed Reality Toolkit for Unity Project is governed, please read [GOVERNANCE.md](./GOVERNANCE.md).
106
105
107
-
All projects under the Mixed Reality Toolkit organization are governed by the Steering Committee. The Steering Committee is responsible for all technical oversight, project approval and oversight, policy oversight, and trademark management for the Organization. To learn more about the Steering Committee, visit this link: https://github.com/MixedRealityToolkit/MixedRealityToolkit-MVG/blob/main/org-docs/CHARTER.md
106
+
All projects under the Mixed Reality Toolkit organization are governed by the Steering Committee. The Steering Committee is responsible for all technical oversight, project approval and oversight, policy oversight, and trademark management for the Organization. To learn more about the Steering Committee, visit this link: <https://github.com/MixedRealityToolkit/MixedRealityToolkit-MVG/blob/main/org-docs/CHARTER.md>
Copy file name to clipboardExpand all lines: XRI2TOXRI3MIGRATIONGUIDE.md
+24-17Lines changed: 24 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,15 +2,15 @@
2
2
3
3
## Introduction
4
4
5
-
Thank you for choosing MRTK as your Mixed Reality framework. MRTK has been upgraded to follow XRI3 patterns and consume [Unity's XR Interaction Toolkit 3+](https://docs.unity3d.com/Packages/[email protected]/manual/whats-new-3.0.html) package. The upgrade encompasses various changes from the previous MRTK version and we want to share our experience during the upgrade so that the community is aware of the changes that had to be implemented. We also want to provide an overall roadmap for others to do their own upgrades in their forks or propietary solutions and therefore we created this guide. We created this guide to empower you and your organization to achieve more in Mixed Reality solutions.
5
+
Thank you for choosing MRTK as your Mixed Reality framework. MRTK has been upgraded to follow XRI3 patterns and consume [Unity's XR Interaction Toolkit 3+](https://docs.unity3d.com/Packages/[email protected]/manual/whats-new-3.0.html) package. The upgrade encompasses various changes from the previous MRTK version and we want to share our experience during the upgrade so that the community is aware of the changes that had to be implemented. We also want to provide an overall roadmap for others to do their own upgrades in their forks or proprietary solutions and therefore we created this guide. We created this guide to empower you and your organization to achieve more in Mixed Reality solutions.
6
6
7
7
## Original MRTK rig structure
8
8
9
9
Previous to XRI3 upgrade the MRTK3 rig had a structure similar to the one shown in the next figure:
The MRTK3 rig prefab is the root GameObject with the Camera Offset ([XROrigin](https://docs.unity3d.com/Packages/[email protected]/api/Unity.XR.CoreUtils.XROrigin.html)) child that has the multiple controllers (LeftHand, RightHand, and Gaze) as children. Next is a screenshot of the now obsolete MRTK XR Rig.
13
+
The MRTK3 rig prefab is the root GameObject with the Camera Offset ([XROrigin](https://docs.unity3d.com/Packages/[email protected]/api/Unity.XR.CoreUtils.XROrigin.html)) child that has the multiple controllers (LeftHand, RightHand, and Gaze) as children. Next is a screenshot of the now obsolete MRTK XR Rig.
In essence, the main difference is that the [XRController](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.InputSystem.XR.XRController.html) component has been removed and replaced with a [Tracked Pose Driver](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.InputSystem.XR.TrackedPoseDriver.html) component which stores references to the Position, Rotation, and Tracking State actions (these can be and are the same as in the old structure). The other input actions (e.g. Select, Activate, UIPress, etc) are moved from the Controller to the Interactor. They are stored in fields already defined in the [Unity's XR Interaction Toolkit 3+](https://docs.unity3d.com/Packages/[email protected]/manual/whats-new-3.0.html) package.
25
+
In essence, the main difference is that the [XRController](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.InputSystem.XR.XRController.html) component has been removed and replaced with a [Tracked Pose Driver](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.InputSystem.XR.TrackedPoseDriver.html) component which stores references to the Position, Rotation, and Tracking State actions (these can be and are the same as in the old structure). The other input actions (e.g. Select, Activate, UIPress, etc) are moved from the Controller to the Interactor. They are stored in fields already defined in the [Unity's XR Interaction Toolkit 3+](https://docs.unity3d.com/Packages/[email protected]/manual/whats-new-3.0.html) package.
26
26
27
-
The XRI3 migration consisted of a set of steps to remove deprecated components and reference the existing Input Actions in their new homes. We recommend that the first step is to move the Position, Rotation and Tracking State actions to their new home according to the new [Unity's XR Interaction Toolkit 3+](https://docs.unity3d.com/Packages/[email protected]/manual/whats-new-3.0.html).
27
+
The XRI3 migration consisted of a set of steps to remove deprecated components and reference the existing Input Actions in their new homes. We recommend that the first step is to move the Position, Rotation and Tracking State actions to their new home according to the new [Unity's XR Interaction Toolkit 3+](https://docs.unity3d.com/Packages/[email protected]/manual/whats-new-3.0.html).
28
28
29
-
## Step 1 - Move Position, Rotation and Tracking State actions
29
+
## Step 1 - Move Position, Rotation, and Tracking State actions
30
30
31
-
Unity introduced a new [Tracked Pose Driver](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.InputSystem.XR.TrackedPoseDriver.html) component which is the new home for the Position, Rotation, and Tracking State input actions. Add such component (or a class derived from it) to your controller(s) and add references to the already existing Position, Rotation, and Tracking State actions that were referenced in the removed XRController, as shown the next figure:
31
+
Unity introduced a new [Tracked Pose Driver](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.InputSystem.XR.TrackedPoseDriver.html) component which is the new home for the Position, Rotation, and Tracking State input actions. Add such component (or a class derived from it) to your controller(s) and add references to the already existing Position, Rotation, and Tracking State actions that were referenced in the removed XRController, as shown the next figure:
## Step 2 - Implement your own Model functionality
36
36
37
-
The next step would be to implement your own controller Model functionality if you use it at all. Unity kindly shared that they have no plans to implement a new home for the Model functionality of the [XRController](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.InputSystem.XR.XRController.html) because of its simplicity so we had to implement it. Fortunately, they are correct and their implementation is quite easy, we recommend you to check MRTK's HandModel MonoBehaviour for an example of its implementation. The next figure shows the new home for the [XRController](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.InputSystem.XR.XRController.html) Model functionality in the new MRTK Controller:
37
+
The next step would be to implement your own controller Model functionality if you use it at all. Unity kindly shared that they have no plans to implement a new home for the Model functionality of the [XRController](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.InputSystem.XR.XRController.html) because of its simplicity so we had to implement it. Fortunately, they are correct and their implementation is quite easy, we recommend you to check MRTK's HandModel MonoBehaviour for an example of its implementation. The next figure shows the new home for the [XRController](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.InputSystem.XR.XRController.html) Model functionality in the new MRTK Controller:
As you make progress in upgrading your Controllers and Interactors to XRI3 it is a good idea to keep an eye on the deprecated XR Controller Configuration Input Compatibility Mode field. This mode controls whether the Interactor uses the new input readers or use the deprecated XR Controller component as per [Unity's changelog](https://docs.unity3d.com/Packages/[email protected]/changelog/CHANGELOG.html#changed-3). It defaults to *Automatic*, however, **<u>this behavior may show false-positive correct behaviors</u>** if you have not removed the [XRController](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.InputSystem.XR.XRController.html) component from the Controller.
43
+
As you make progress in upgrading your Controllers and Interactors to XRI3, it is a good idea to keep an eye on the deprecated XR Controller Configuration Input Compatibility Mode field. This mode controls whether the Interactor uses the new input readers or use the deprecated XR Controller component as per [Unity's changelog](https://docs.unity3d.com/Packages/[email protected]/changelog/CHANGELOG.html#changed-3). It defaults to *Automatic*, however, **<u>this behavior may show false-positive correct behaviors</u>** if you have not removed the [XRController](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.InputSystem.XR.XRController.html) component from the Controller.
44
44
45
-
The Input Compatibility Mode can be found via Inspector under the *(Deprecated) XR Controller Configuration* group as shown next:
45
+
The Input Compatibility Mode can be found via Inspector under the *(Deprecated) XR Controller Configuration* group as shown here:
## Step 3 - Move the remaining [XRController](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.InputSystem.XR.XRController.html) input actions to their respective Interactors
50
50
51
-
Once you have moved the device tracking input actions to the [Tracked Pose Driver](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.InputSystem.XR.TrackedPoseDriver.html) component and implemented your own Model functionality then you can move the remaining input actions from the original [XRController](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.InputSystem.XR.XRController.html) to the Interactors themselves. The following image highlights the new controller prefab interactors fields that we needed to update for the XRI3 migration.
51
+
Once you have moved the device tracking input actions to the [Tracked Pose Driver](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.InputSystem.XR.TrackedPoseDriver.html) component and implemented your own Model functionality then you can move the remaining input actions from the original [XRController](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.InputSystem.XR.XRController.html) to the Interactors themselves. The following image highlights the new controller prefab interactors fields that we needed to update for the XRI3 migration.
As you may have noticed already MRTK controller prefabs now have a new child in which we group Input actions for pinch and UI interaction. These are shown in the next figure:
57
+
As you may have noticed that MRTK controller prefabs now have a new child in which we group Input actions for pinch and UI interaction. These are shown in the next figure:
We added this child + script as a workaround for devices without interaction profiles for hands, however, if your solution does not have a use-case without hands interactions profiles then you can safely map the MRTK's InputReaders' input actions directly in their corresponding Interactor fields.
61
+
We added this child + script as a workaround for devices without interaction profiles for hands; however, if your solution does not have a use-case without hands interactions profiles then you can safely map the MRTK's InputReaders' input actions directly in their corresponding Interactor fields.
62
62
63
63
### TrackedPoseDriver and ModeManagedRoot references
64
64
65
65
In addition to the InputReaders child you may have also noticed that MRTK interactors now have two new fields: [Tracked Pose Driver](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.InputSystem.XR.TrackedPoseDriver.html) and Mode Managed Root, as shown next:
66
66
67
67
68
68
69
-
These are just convenient fields to hold references to the parent controller [Tracked Pose Driver](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.InputSystem.XR.TrackedPoseDriver.html) component and GameObject. These are not mandatory for a successful XRI3 migration but they facilitate coding as well as writing Unity-tests.
69
+
These are just convenient fields to hold references to the parent controller [Tracked Pose Driver](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.InputSystem.XR.TrackedPoseDriver.html) component and GameObject. These are not mandatory for a successful XRI3 migration but they facilitate coding as well as writing Unitytests.
70
70
71
71
## Step 4 - Update scripts
72
72
@@ -75,12 +75,19 @@ For the XRI3 migration we modified our scripts with two goals:
75
75
* Adhere to the new XRI3 patterns.
76
76
* Provide backward compatibility.
77
77
78
-
As you will notice in the code many of our changes query the Input Compatibility Mode field to differentiate between XRI2 functionality and XRI3 functionality. This is not mandatory for a successful XRI3 migration, however, we wanted to create a smooth transition for all of you and did our best to ensure backward compatibily as you migrate your forks or solutions.
78
+
As you will notice in the code many of our changes query the Input Compatibility Mode field to differentiate between XRI2 functionality and XRI3 functionality. This is not mandatory for a successful XRI3 migration, however, we wanted to create a smooth transition for all of you and did our best to ensure backward compatibility as you migrate your forks or solutions.
79
79
80
80
We encourage you to check the code in each script as well as the commit history to get a sense of the changes that were needed.
81
81
82
-
## Step 5 - Update Unity-tests
82
+
If you have any custom interactors based on MRTK interfaces, the following table will help you move from deprecated MRTK interfaces to XRI3-compatible interfaces:
83
83
84
-
Last but not least, Unity-tests! We created several new Unity-tests to ensure the correct functionality of the new XRI3 MRTK rig as well as the old functionality. We encourage you to visit the code and commit history related to Unity-tests to get a sense of the changes. Note that the changes focus mostly on where and how the input actions are queried but the overall functionality test remains the same.
Thank you for reading this guide, we hope it empowers you to achieve more. Please feel free to submit an issue if you have comments or questions.
89
+
## Step 5 - Update Unity tests
90
+
91
+
Last but not least, Unity tests! We created several new Unity tests to ensure the correct functionality of the new XRI3 MRTK rig as well as the old functionality. We encourage you to visit the code and commit history related to Unity tests to get a sense of the changes. Note that the changes focus mostly on where and how the input actions are queried but the overall functionality test remains the same.
92
+
93
+
Thank you for reading this guide, we hope it empowers you to achieve more. Please feel free to submit an issue if you have comments or questions.
0 commit comments