Microsoft Mixed Reality Toolkit release notes
This release of the Microsoft Mixed Reality Toolkit supports the following devices and platforms.
- Microsoft HoloLens 2
- Microsoft HoloLens (1st gen)
- Windows Mixed Reality Immersive headsets
- OpenVR
- (Experimental) Unity 2019.3 XR platform
- Mobile AR via Unity AR Foundation
- Android
- iOS
- Ultraleap Hand Tracking
The following software is required.
- Microsoft Visual Studio (2017 or 2019) Community Edition or higher
- Windows 10 SDK 18362 or later (installed by the Visual Studio Installer)
- Unity 2018.4 LTS or 2019 (2019.3 recommended)
Download
Microsoft.MixedReality.Toolkit.Unity.Foundation.2.4.0.unitypackage Microsoft.MixedReality.Toolkit.Unity.Extensions.2.4.0.unitypackage Microsoft.MixedReality.Toolkit.Unity.Examples.2.4.0.unitypackage Microsoft.MixedReality.Toolkit.Unity.Tools.2.4.0.unitypackage
Other files can be found on the GitHub release page
NuGet requirements
If importing the Mixed Reality Toolkit NuGet packages, the following software is recommended.
What's new in 2.4.0
Ultraleap Hand Tracking Support
The Leap Motion Data Provider enables articulated hand tracking for VR applications and is also useful for rapid prototyping in the editor. The data provider can be configured to use the Leap Motion Controller mounted on a headset or placed on a desk face up.
A Leap Motion Controller is required to use this data provider.
Migration window
MRTK now comes with a migration tool that will help you upgrade deprecated components to their newer versions and to keep existing code working even as MRTK makes breaking changes.
It is generally recommended to run the migration tool after pulling a new version of MRTK to ensure that as much of your project will be auto-adjusted to the latest MRTK code.
The migration window can be found in 'Mixed Reality Toolkit > Utilities > Migration Window'. It it part of the Tools package.
It currently supports:
- Upgrading ManipulationHandler and BoundingBox to their newer versions ObjectManipulator and BoundsControl.
- Updating custom button icons to work correctly with the new Button Config Helper.
Note that BoundsControl is still in experimental phase and therefore API or properties might still change in the next version.
MRTK folder layout changes
This version of MRTK modifies the layout of the MRTK folder structure. This change encapsulates all MRTK code into a single folder hierarchy and reduces the total path length of all MRTK files.
| Previous Folder | New Folder |
|---|---|
| MixedRealityToolkit | MRTK\Core |
| MixedRealityToolkit.Examples | MRTK\Examples |
| MixedRealityToolkit.Extensions | MRTK\Extensions |
| MixedRealityToolkit.Providers | MRTK\Providers |
| MixedRealityToolkit.SDK | MRTK\SDK |
| MixedRealityToolkit.Services | MRTK\Services |
| MixedRealityToolkit.Tests | MRTK\Tests |
| MixedRealityToolkit.Tools | MRTK\Tools |
Important
The MixedRealityToolkit.Generated contains customer generated files and remains unchanged.
MRTK Toolbox
The MRTK Toolbox is a Unity editor window utility that makes it easy to discover and spawn MRTK UX prefab components into the current scene. Items can be filtered in view by using the search bar at the top of the window. The toolbox window is designed to spawn MRTK out-of-box prefabs into the current scene.
Tap to Place
Tap to Place is a far interaction component used to easily place a game object on surface. Tap to Place uses a combination of two clicks and head movement to place an object.
Button Config Helper added to Pressable Buttons
This new feature makes it easy to change the icon and text of the buttons. Icon supports quad, sprite, and TextMesh Pro's SDF font texture. See MRTK's Button documentation for the details.
New HoloLens 2-style Toggle Buttons - Checkbox, Switch, Radio
Hand Menu Improvements
Hand menu has been adapted in many applications. One of the biggest issue we found is the accidental false activation while manipulating objects or interacting with other content, etc. New 'Gaze Activation' option added to HandConstraintPalmUp.cs to prevent false activations. With this option, the menu does not accidentally show up, until the user look at the hand.
Hand Menu Examples update
[New] Large menu interaction example 1: Grab & Pull menu to world-lock
[New] Large menu interaction example 2 - Auto world-lock on hand drop
Dialog (Experimental)
Dialog UI has been ported over from HoloToolkit with new HoloLens 2 shell-style design updates.
Dock (Experimental)
This control enables moving objects in and out of predetermined positions, to create palettes, shelves and navigation bars.
Unity Profiler markers
This version of MRTK has added Unity Profiler markers to the input system and data providers. These markers provide detailed information on where time is spent in the MRTK input system that can be used to help optimize applications.
Markers take the format of "[MRTK] ClassWithoutNamespace.Method".
WindowsApiChecker: IsMethodAvailable(), IsPropertyAvailable() and IsTypeAvailable()
This version of MRTK adds three new methods to the WindowsApiChecker class: IsMethodAvailable, IsPropertyAvailable and IsTypeAvailable. These methods allow for checking for feature support on Windows 10 and are preferred over using the UniversalApiContractV#_IsAvailable properties.
Helpers to get text input fields working with MixedRealityKeyboard for UnityUI, TextMeshPro (Experimental)
We have introduced two helper components, UI_KeyboardInputField and TMP_KeyboardInputField that can be added to text input fields in Unity UI to enable the HoloLens 2 and Windows Mixed Reality Keyboard to show up when the fields are clicked.
For more information, see - Mixed Reality Keyboard Helpers.
Grid Object Collection Alignment Options
We have added the ability to choose how the elements in the grid are aligned, whether they are aligned in the center or along the left/right axis (top/bottom axis when doing row then column layout)
Grid Object Collection Anchor Changes
We made changes to Grid Object Collection behavior to be more in line with Unity's layout group behaviors by aligning the anchor along an object's central axis. The old Grid Object Collection behavior can be toggled with the AnchorAlongAxis field.
Adjusted input simulation camera control
Camera control speed using in-editor input simulation is slower for a smoother experience and is now untied from framerate. Fast camera control now activated with Right Shift instead of Right Ctrl
Hands-free GGV input simulation
We've enabled the ability to interact with objects without bringing hands within the in-editor input simulation service. Rotate the camera so that the gaze cursor is over an interactable object, and click on the left mouse button to interact with it.
Button Config Helper
The Button Config Helper is an editor feature that makes it easier to customize MRTK buttons. It's now much easier to:
- Update the button label text
- Add a button click event listener
- Change the button icon
Audio Spatializer Selection in MRTK configuration dialog
The audio spatializer can now be specified in the MRTK configuration dialog. Installing new spatializers, such as the Microsoft Spatializer, will re-prompt to allow for easy selection.
Object manipulator graduated to SDK
ObjectManipulator now graduated to SDK and is no longer an experimental feature. This control is replacing the existing ManipulationHandler class which is now deprecated. ObjectManipulator comes with a new more flexible constraint system and correctly responds to physics. A full feature list and guide how to set up can be found in object manipulator documentation. Users can take advantage of the new migration window to upgrade their existing gameobject using ManipulationHandler to ObjectManipulator
Bounds control improvements
We extensively increased test coverage for bounds control this version and addressed one of the biggest pain points of users of bounding box: bounds control will now no longer recreate its visuals on configuration changes. Also it now supports reconfiguring any property during runtime. Also the properties DrawTetherWhenManipulating and HandlesIgnoreCollider are now configurable per handle type.
Breaking changes in 2.4.0
Eye Gaze API
The UseEyeTracking property from GazeProvider implementation of IMixedRealityEyeGazeProvider was renamed to IsEyeTrackingEnabled.
If you did this previously...
if (CoreServices.InputSystem.GazeProvider is GazeProvider gazeProvider)
{
gazeProvider.UseEyeTracking = true;
}
Do this now...
if (CoreServices.InputSystem.GazeProvider is GazeProvider gazeProvider)
{
gazeProvider.IsEyeTrackingEnabled = true;
}
Eye gaze setup
This version of MRTK modifies the steps required for eye gaze setup. The 'IsEyeTrackingEnabled' checkbox can be found in the gaze settings of the input pointer profile. Checking this box will enable eye based gaze, rather then the default head based gaze.
For more information on these changes and complete instructions for eye tracking setup, please see the eye tracking article.
Known issues in 2.4.0
MRTK Configurator dialog does not show 'Enable MSBuild for Unity' in Unity 2019.3
An issue exists where enabling MSBuild for Unity in 2019.3 may result in an infinite loop restoring packages (#7239).
As a workaround, the Microsoft.Windows.DotNetWinRT package can be imported using NuGet for Unity.
Duplicate Assembly Version and Multiple Precompiled Assemblies Unity 2018.4
If the platform is switched from Standalone to UWP and then back to Standalone in Unity 2018.4, the following errors might be in the console:
PrecompiledAssemblyException: Multiple precompiled assemblies with the same name Microsoft.Windows.MixedReality.DotNetWinRT.dll included for the current platform. Only one assembly with the same name is allowed per platform. Assembly paths
Assets\MRTK\Examples\Demos\HandTracking\Scenes\Utilities\InspectorFields\AssemblyInfo.cs(6,12): error CS0579: Duplicate 'AssemblyVersion' attribute
These errors are due to issues in the deletion process with MSBuildForUnity. To resolve the issue, while in Standalone, delete the Dependencies folder at the root of Assets and restart unity.
For a more details see Issue 7948.
Applications appearing as a 2D slate on Unity 2019.3
When using Unity 2019.3, enabling XR support does not configure a default SDK (legacy) or plugin (XR Mangement). This results in applications being constrained to a 2D slate. Details on resolving this can be found in the Building and Deploying MRTK article.
Unity 2019.3: ARM build architecture
There is a known issue in Unity 2019.3 that causes errors when selecting ARM as the build architecture in Visual Studio. The recommended work around is to build for ARM64. If that is not an option, please disable Graphics Jobs in Edit > Project Settings > Player > Other Settings. For more information see Building and Deploying.
Runtime profile swapping
MRTK does not fully support profile swapping at runtime. This feature is being investigated for a future release. Please see issues 4289, 5465 and 5466 for more information.
Unity 2018: .NET Backend and AR Foundation
There is an issue in Unity 2018 where, building a Universal Windows Platform project using the .NET scripting backend, the Unity AR Foundation package will fail.
To work around this issue, please perform one of the following steps:
- Switch the scripting backend to IL2CPP
- In the Build Settings window, uncheck **Unity C# Projects"