Object Manipulator — MRTK3

ObjectManipulator enables intuitive manipulation of objects in 3D space with any input device or modality. It performs a similar task to the XRI XRGrabInteractable, but offers additional features and mixed reality-specific interactions. While the XRGrabInteractable is fully compatible with our interactors (and the opposite is also true), we still recommend using our implementation for the best experience.

Note

ObjectManipulator is specifically designed for manipulating 3D objects directly and intuitively. If you're looking for common UI interactions like sliders or buttons, see our sliders and buttons articles instead. Avoid using ObjectManipulator to write micro-interactions.

Architecture

In MRTK v2, most of the complex logic and math for the different types of input were handled by ObjectManipulator itself. A separate codepath had to be maintained for each type of interaction, resulting in less flexibility when introducing new types of interactions. In MRTK3, the interactor is responsible for the specifics of how a particular type of input is translated into a manipulation. ObjectManipulator simply listens to these interactors and applies the relevant transformation to the object. As a result, ObjectManipulator in MRTK3 is significantly simpler and smaller in scope. See the Interactor architecture for descriptions of how interactors communicate through their attach transforms.

n-handed manipulations

ObjectManipulator supports any number of participating interactors, allowing for generalizable interaction behavior across one, two, and even n-handed manipulations. Generally, the geometric centroid of all participating interactors' attachTransforms is used for multi-handed interactions. As an XRI interactable, it's compatible with any type of interactor that submits a well-behaved attach transform.

If you want to not allow multi-handed manipulations, set the XRI Selection Mode to Single. We alias this property in the inspector to the more specific name Multiselect Mode to avoid confusion with our MRTK Selection Mode, which is used to specify whether an interactable can be toggled (see the Button documentation for further clarification.)

Constraints

ObjectManipulator uses the Constraints API to constrain manipulations. See the Constraints documentation for more information.

Manipulation logic injection

Developers can customize the manipulation behavior of ObjectManipulator without needing to subclass or otherwise modify the script itself. Simply write a new ManipulationLogic<T> and specify the type in the inspector with the ManipulationLogicTypes property.

Similarly, developers can customize the smoothing behavior by writing a new implementation of ITransformSmoothingLogic and specifying the type in the inspector with the TransformSmoothingLogicType property.

Important

If you find yourself writing new manipulation logic types for a new kind of interaction or input device, you're probably going down the wrong path. The existing manipulation logic should work for arbitrary input types as long as the attach transform is well-behaved. Consider adjusting or writing a new interactor instead. Read the Interactor architecture documentation and the Interactable architecture documentation for more information on how to write well-behaved interaction logic.