Updating from RC2 to 2.0.0
Between the RC2 and 2.0.0 releases of the Microsoft Mixed Reality Toolkit, changes were made that may impact existing projects. This document describes those changes and how to update projects to the 2.0.0 release.
API changes
Since the release of RC2, there have been a number of API changes including some that may break existing projects. The following sections describe the changes that have occurred between the RC2 and 2.0.0 releases.
- MixedRealityToolkit
- CoreServices
- IMixedRealityRaycastProvider
- Event System
- Spatial Awareness
- Solvers
- Buttons
- Clipping Sphere
- NearInteractionTouchable and PokePointer
- ReadOnlyAttribute
- PointerClickHandler
- HoloLens Clicker Support
- InteractableHighlight
- HandInteractionPanZoom
MixedRealityToolkit
The following public properties on the MixedRealityToolkit object have been deprecated.
RegisteredMixedRealityServices
no longer contains the collection of registered extensions services and data providers.
To access extension services, use MixedRealityServiceRegistry.TryGetService<T>
. To access data providers, cast the service instance to IMixedRealityDataProviderAccess
and use GetDataProvider<T>
.
Use MixedRealityServiceRegistry
or CoreServices
instead for the following deprecated properties
ActiveSystems
InputSystem
BoundarySystem
CameraSystem
SpatialAwarenessSystem
TeleportSystem
DiagnosticsSystem
SceneSystem
CoreServices
The CoreServices
class is the replacement for the static system accessors (ex: BoundarySystem) found in the MixedRealityToolkit
object.
Important
The MixedRealityToolkit
system accessors have been deprecated in version 2.0.0 and will be removed in a future release of the MRTK.
The following code example illustrates the old and the new pattern.
// Old
GameObject playAreaVisualization = MixedRealityToolkit.BoundarySystem?.GetPlayAreaVisualization();
// New
GameObject playAreaVisualization = CoreServices.BoundarySystem?.GetPlayAreaVisualization();
Using the new CoreSystem class will ensure that your application code will not need updating if you change the application to use a different service registrar (ex: one of the experimental service managers).
IMixedRealityRaycastProvider
With the addition of the IMixedRealityRaycastProvider, the input system configuration profile was changed. If you have a custom profile, you may receive the errors in the following image when you run your application.
To fix these, please add an IMixedRealityRaycastProvider instance to your input system profile.
Event System
Changes
- The
IMixedRealityEventSystem
old API methodsRegister
andUnregister
have been marked as obsolete. They are preserved for backwards compatibility. InputSystemGlobalListener
has been marked as obsolete. Its functionality has not changed.BaseInputHandler
base class has been changed fromInputSystemGlobalListener
toInputSystemGlobalHandlerListener
. This is a breaking change for any descendants ofBaseInputHandler
.
Motivation behind the change
The old event system API Register
and Unregister
could potentially cause multiple issues in runtime, main being:
- If a component registers for global events, it would receive global input events of all types.
- If one of the components on an object registers for global input events, all components on this object will receive global input events of all types.
- If two components on the same object register to global events, and then one is disabled in runtime, the second one stops receiving global events.
New API RegisterHandler
and UnregisterHandler
:
- Provides an explicit and granular control over which input events should be listened to globally and which should be focused-based.
- Allows multiple components on the same object to listen to global events independently on each other.
How to migrate
- If you have been calling
Register
/Unregister
API directly before, replace these calls with calls toRegisterHandler
/UnregisterHandler
. Use handler interfaces you implement as generic parameters. If you implement multiple interfaces, and several of them listen to global input events, callRegisterHandler
multiple times. - If you have been inheriting from
InputSystemGlobalListener
, change inheritance toInputSystemGlobalHandlerListener
. ImplementRegisterHandlers
andUnregisterHandlers
abstract methods. In the implementation callinputSystem.RegisterHandler
(inputSystem.UnregisterHandler
) to register on all handler interfaces you want to listen global events for. - If you have been inheriting from
BaseInputHandler
, implementRegisterHandlers
andUnregisterHandlers
abstract methods (same as forInputSystemGlobalListener
).
Examples of migration
// Old
class SampleHandler : MonoBehaviour, IMixedRealitySourceStateHandler, IMixedRealityHandJointHandler
{
private void OnEnable()
{
InputSystem?.Register(gameObject);
}
private void OnDisable()
{
InputSystem?.Unregister(gameObject);
}
}
// Migrated
class SampleHandler : MonoBehaviour, IMixedRealitySourceStateHandler, IMixedRealityHandJointHandler
{
private void OnEnable()
{
InputSystem?.RegisterHandler<IMixedRealitySourceStateHandler>(this);
InputSystem?.RegisterHandler<IMixedRealityHandJointHandler>(this);
}
private void OnDisable()
{
InputSystem?.UnregisterHandler<IMixedRealitySourceStateHandler>(this);
InputSystem?.UnregisterHandler<IMixedRealityHandJointHandler>(this);
}
}
// Old
class SampleHandler2 : InputSystemGlobalListener, IMixedRealitySpeechHandler
{
}
// Migrated
class SampleHandler2 : InputSystemGlobalHandlerListener, IMixedRealitySpeechHandler
{
private void RegisterHandlers()
{
InputSystem?.RegisterHandler<IMixedRealitySpeechHandler>(this);
}
private void UnregisterHandlers()
{
InputSystem?.UnregisterHandler<IMixedRealitySpeechHandler>(this);
}
}
// Alternative migration
class SampleHandler2 : MonoBehaviour, IMixedRealitySpeechHandler
{
private void OnEnable()
{
IMixedRealityInputSystem inputSystem;
if (MixedRealityServiceRegistry.TryGetService<IMixedRealityInputSystem>(out inputSystem))
{
inputSystem?.RegisterHandler<IMixedRealitySpeechHandler>(this);
}
}
private void OnDisable()
{
IMixedRealityInputSystem inputSystem;
if (MixedRealityServiceRegistry.TryGetService<IMixedRealityInputSystem>(out inputSystem))
{
inputSystem?.UnregisterHandler<IMixedRealitySpeechHandler>(this);
}
}
}
Spatial Awareness
The IMixedRealitySpatialAwarenessSystem and IMixedRealitySpatialAwarenessObserver interfaces have taken multiple breaking changes as described below.
Changes
The following method(s) have been renamed to better describe their usage.
IMixedRealitySpatialAwarenessSystem.CreateSpatialObjectParent
has been renamed toIMixedRealitySpatialAwarenessSystem.CreateSpatialAwarenessObservationParent
to clarify its usage.
Additions
Based on customer feedback, support for easy removal of previously observed spatial awareness data has been added.
IMixedRealitySpatialAwarenessSystem.ClearObservations()
IMixedRealitySpatialAwarenessSystem.ClearObservations<T>(string name)
IMixedRealitySpatialAwarenessObserver.ClearObservations()
Solvers
Some solver components and the SolverHandler manager class has changed to fix various bugs and for more intuitive usage.
SolverHandler
- Class no longer extends from
ControllerFinder
TrackedObjectToReference
public property deprecated and has been renamed toTrackedTargetType
TrackedObjectType
deprecates left & right controller values. Instead useMotionController
orHandJoint
values and update newTrackedHandedness
property to limit tracking to left or right controller
InBetween
TrackedObjectForSecondTransform
public property deprecated and has been renamed toSecondTrackedObjectType
AttachSecondTransformToNewTrackedObject()
has been removed. To update the solver, modify the public properties (i.eSecondTrackedObjectType
)
SurfaceMagnetism
MaxDistance
public property deprecated and has been renamed toMaxRaycastDistance
CloseDistance
public property deprecated and has been renamed toClosestDistance
- Default value for
RaycastDirectionMode
is nowTrackedTargetForward
which raycasts in the direction of the tracked target transform forward OrientationMode
enum values,Vertical
andFull
, have been renamed toTrackedTarget
andSurfaceNormal
respectivelyKeepOrientationVertical
public property has been added to control whether orientation of associated GameObject remains vertical
Buttons
PressableButton
now hasDistanceSpaceMode
property set toLocal
as default. This allows buttons to be scaled while still be pressable
Clipping Sphere
The ClippingSphere interface has changed to mirror the APIs found in the ClippingBox and ClippingPlane.
Changes
The ClippingSphere's Radius property is now implicitly calculated based on the transform scale. Before developers would have to specify the radius of the ClippingSphere in the inspector. If you want to change the radius, just update the transform scale of the transform as you normally would.
NearInteractionTouchable and PokePointer
- NearInteractionTouchable does not handle Unity UI canvas touching any longer. The NearInteractionTouchableUnityUI class must be used for Unity UI touchables now.
- ColliderNearInteractionTouchable is the new base class for touchables based on colliders, i.e. every touchable except NearInteractionTouchableUnityUI.
- BaseNearInteractionTouchable.DistFront has been moved and renamed to PokePointer.TouchableDistance This is the distance and which the PokePointer can interact with touchables. Previously each touchable had it's own maximum interaction distance, but now this is defined in the PokePointer which allows better optimization.
- BaseNearInteractionTouchable.DistBack has been renamed to PokeThreshold This makes it clear that PokeThreshold is the counterpart to DebounceThreshold. A touchable is activated when the PokeThreshold is crossed, and released when DebounceThreshold is crossed.
ReadOnlyAttribute
The Microsoft.MixedReality.Toolkit
namespace has been added to ReadOnlyAttribute
, BeginReadOnlyGroupAttribute
, and EndReadOnlyGroupAttribute
.
PointerClickHandler
The PointerClickHandler
class has been deprecated. The PointerHandler
should be used instead, it provides the same functionality.
HoloLens clicker support
The HoloLens clicker's controller mappings have changed from being an unhanded WindowsMixedRealityController
to being an unhanded WindowsMixedRealityGGVHand
. To account for this, an automatic updater will run the first time you open your ControllerMapping profile. Please open any custom profiles at least once after upgrading to 2.0.0 in order to trigger this one-time migration step.
InteractableHighlight
The InteractableHighlight
class has been deprecated. The InteractableOnFocus
class and FocusInteractableStates
asset should be used instead. To create a new Theme
asset for the InteractableOnFocus
, right click in the project window and select Create > Mixed Reality Toolkit > Interactable > Theme.
HandInteractionPanZoom
HandInteractionPanZoom
has been moved to the UI namespace as it was not an input component. HandPanEventData
has also been moved into this namespace, and simplified to correspond with other UI event data.
Assembly name changes
In The 2.0.0 release, all of the official Mixed Reality Toolkit assembly names and their associated assembly definition (.asmdef) files have been updated to fit the following pattern.
Microsoft.MixedReality.Toolkit[.<name>]
In some instances, multiple assemblies have been merged to create better unity of their contents. If your project uses custom .asmdef files, they may require updating.
The following tables describe how the RC2 .asmdef file names map to the 2.0.0 release. All assembly names match the .asmdef file name.
MixedRealityToolkit
RC2 | 2.0.0 |
---|---|
MixedRealityToolkit.asmdef | Microsoft.MixedReality.Toolkit.asmdef |
MixedRealityToolkit.Core.BuildAndDeploy.asmdef | Microsoft.MixedReality.Toolkit.Editor.BuildAndDeploy.asmdef |
MixedRealityToolkit.Core.Definitions.Utilities.Editor.asmdef | Removed, use Microsoft.MixedReality.Toolkit.Editor.Utilities.asmdef |
MixedRealityToolkit.Core.Extensions.EditorClassExtensions.asmdef | Microsoft.MixedReality.Toolkit.Editor.ClassExtensions.asmdef |
MixedRealityToolkit.Core.Inspectors.asmdef | Microsoft.MixedReality.Toolkit.Editor.Inspectors.asmdef |
MixedRealityToolkit.Core.Inspectors.ServiceInspectors.asmdef | Microsoft.MixedReality.Toolkit.Editor.ServiceInspectors.asmdef |
MixedRealityToolkit.Core.UtilitiesAsync.asmdef | Microsoft.MixedReality.Toolkit.Async.asmdef |
MixedRealityToolkit.Core.Utilities.Editor.asmdef | Microsoft.MixedReality.Toolkit.Editor.Utilities.asmdef |
MixedRealityToolkit.Utilities.Gltf.asmdef | Microsoft.MixedReality.Toolkit.Gltf.asmdef |
MixedRealityToolkit.Utilities.Gltf.Importers.asmdef | Microsoft.MixedReality.Toolkit.Gltf.Importers.asmdef |
MixedRealityToolkit.Providers
RC2 | 2.0.0 |
---|---|
MixedRealityToolkit.Providers.OpenVR.asmdef | Microsoft.MixedReality.Toolkit.Providers.OpenVR.asmdef |
MixedRealityToolkit.Providers.WindowsMixedReality.asmdef | Microsoft.MixedReality.Toolkit.Providers.WindowsMixedReality.asmdef |
MixedRealityToolkit.Providers.WindowsVoiceInput.asmdef | Microsoft.MixedReality.Toolkit.Providers.WindowsVoiceInput.asmdef |
MixedRealityToolkit.Services
RC2 | 2.0.0 |
---|---|
MixedRealityToolkit.Services.BoundarySystem.asmdef | Microsoft.MixedReality.Toolkit.Services.BoundarySystem.asmdef |
MixedRealityToolkit.Services.CameraSystem.asmdef | Microsoft.MixedReality.Toolkit.Services.CameraSystem.asmdef |
MixedRealityToolkit.Services.DiagnosticsSystem.asmdef | Microsoft.MixedReality.Toolkit.Services.DiagnosticsSystem.asmdef |
MixedRealityToolkit.Services.InputSimulation.asmdef | Microsoft.MixedReality.Toolkit.Services.InputSimulation.asmdef |
MixedRealityToolkit.Services.InputSimulation.Editor.asmdef | Microsoft.MixedReality.Toolkit.Services.InputSimulation.Editor.asmdef |
MixedRealityToolkit.Services.InputSystem.asmdef | Microsoft.MixedReality.Toolkit.Services.InputSystem.asmdef |
MixedRealityToolkit.Services.Inspectors.asmdef | Microsoft.MixedReality.Toolkit.Services.InputSystem.Editor.asmdef |
MixedRealityToolkit.Services.SceneSystem.asmdef | Microsoft.MixedReality.Toolkit.Services.SceneSystem.asmdef |
MixedRealityToolkit.Services.SpatialAwarenessSystem.asmdef | Microsoft.MixedReality.Toolkit.Services.SpatialAwarenessSystem.asmdef |
MixedRealityToolkit.Services.TeleportSystem.asmdef | Microsoft.MixedReality.Toolkit.Services.TeleportSystem.asmdef |
MixedRealityToolkit.SDK
RC2 | 2.0.0 |
---|---|
MixedRealityToolkit.SDK.asmdef | Microsoft.MixedReality.Toolkit.SDK.asmdef |
MixedRealityToolkit.SDK.Inspectors.asmdef | Microsoft.MixedReality.Toolkit.SDK.Inspectors.asmdef |
MixedRealityToolkit.Examples
RC2 | 2.0.0 |
---|---|
MixedRealityToolkit.Examples.asmdef | Microsoft.MixedReality.Toolkit.Examples.asmdef |
MixedRealityToolkit.Examples.Demos.Gltf.asmdef | Microsoft.MixedReality.Toolkit.Demos.Gltf.asmdef |
MixedRealityToolkit.Examples.Demos.StandardShader.Inspectors.asmdef | Microsoft.MixedReality.Toolkit.Demos.StandardShader.Inspectors.asmdef |
MixedRealityToolkit.Examples.Demos.Utilities.InspectorFields.asmdef | Microsoft.MixedReality.Toolkit.Demos.InspectorFields.asmdef |
MixedRealityToolkit.Examples.Demos.Utilities.InspectorFields.Inspectors.asmdef | Microsoft.MixedReality.Toolkit.Demos.InspectorFields.Inspectors.asmdef |
MixedRealityToolkit.Examples.Demos.UX.Interactables.asmdef | Microsoft.MixedReality.Toolkit.Demos.UX.Interactables.asmdef |