API reference

Select your platform

No SDKs available

No versions available

Overview

MRUK Class

Extends MonoBehaviour

The MRUK class provides a comprehensive suite of utility functions designed work with scene data and to facilitate the management and querying of scenes within the Unity editor.

This class is integral for developers working within the MR utility kit framework, offering capabilities such as to load scenes, to register callbacks for scene events, to manage room and anchor data, and handle world locking to ensure virtual objects remain synchronized with the real world. Use the SceneDataSource enum to specify positioning strategies and data source, (such as device data, prefabs or json files). Only one instance of this class can exist in a scene. When using world locking by setting EnableWorldLock to true, make sure to use the OVRCameraRig component in your scene, as it is used to determine the camera's position and orientation.

Fields

EnableWorldLock : bool	When world locking is enabled the position and rotation of the OVRCameraRig/TrackingSpace transform will be adjusted each frame to ensure that the room anchors are where they should be relative to the camera position. This is necessary to ensure the position of the virtual objects in the world do not get out of sync with the real world. Make sure that your scene is making use of the OVRCameraRig component. Signature bool EnableWorldLock
SceneSettings : MRUKSettings	Contains all the information regarding data loading. Signature MRUKSettings SceneSettings
TrackingSpaceOffset : Matrix4x4	When the EnableWorldLock is enabled, MRUK will modify the TrackingSpace transform, overwriting any manual changes. Use this field to change the position and rotation of the TrackingSpace transform when the world locking is enabled. Signature Matrix4x4 TrackingSpaceOffset

Properties

Instance : MRUK [Get]	Gets the singleton instance of the MRUK class. Signature MRUK Instance
IsInitialized : bool [Get]	Gets a value indicating whether the component has been initialized. When using RegisterSceneLoadedCallback to register a callback, it will be triggered right away if the component is already initialized. Signature bool IsInitialized
IsWorldLockActive : bool [Get]	This property indicates if world lock is currently active. This means that EnableWorldLock is enabled and the current room has successfully been localized. In some cases such as when the headset goes into standby, the user moves to another room and comes back out of standby the headset may fail to localize and this property will be false. The property may become true again once the device is able to localise the room again (e.g. if the user walks back into the original room). This property can be used to show a UI panel asking the user to return to their room. Signature bool IsWorldLockActive
QRCodeTrackingSupported : bool [Get]	Whether QR code tracking is supported. If QR code tracking is supported, you can enable it by setting the OVRAnchor.TrackerConfiguration.QRCodeTrackingEnabled property on the TrackerConfiguration. Signature bool QRCodeTrackingSupported
RoomCreatedEvent : UnityEvent< MRUKRoom > [Get]	This event is triggered when a new room is created from scene capture. Useful for apps to intercept the room creation and do some custom logic with the new room. Signature UnityEvent<MRUKRoom> RoomCreatedEvent
RoomRemovedEvent : UnityEvent< MRUKRoom > [Get]	Event that is triggered when a room is removed. Useful for apps to intercept the room removal and do some custom logic with the room just removed. Signature UnityEvent<MRUKRoom> RoomRemovedEvent
Rooms : List< MRUKRoom > [Get]	List of all the rooms in the scene. Signature List<MRUKRoom> Rooms
RoomUpdatedEvent : UnityEvent< MRUKRoom > [Get]	Event that is triggered when a room is updated, this can happen when the user adds or removes an anchor from the room. Useful for apps to intercept the room update and do some custom logic with the anchors in the room. Signature UnityEvent<MRUKRoom> RoomUpdatedEvent
SceneLoadedEvent : UnityEvent [Get]	Event that is triggered when the scene is loaded. Use RegisterSceneLoadedCallback to register callbacks instead of subscribing directly to this event, as it provides the benefit of having the callback execute immediately if the scene is already loaded. Signature UnityEvent SceneLoadedEvent
TrackerConfiguration : OVRAnchor.TrackerConfiguration [Get]	The current configuration for the tracking service. To request a particular configuration, set the desired values in MRUKSettings.TrackerConfiguration. This property represents the true state of the system. This may differ from what was requested with MRUKSettings.TrackerConfiguration if, for example, some types of trackables are not supported on the current device. Signature OVRAnchor.TrackerConfiguration TrackerConfiguration

Methods

ClearScene ()	Destroys the rooms and all children. Signature void ClearScene() Returns `void`
GetAnchors ()	Get a flat list of all Anchors in the scene. Signature List< MRUKAnchor > GetAnchors() Returns `List< MRUKAnchor >` A list of MRUKAnchor objects representing all the anchors in the current room.
GetCurrentRoom ()	Returns the current room the headset is in. If the headset is not in any given room then it will return the room the headset was last in when this function was called. If the headset hasn't been in a valid room yet then return the first room in the list. If no rooms have been loaded yet then return null. Signature MRUKRoom GetCurrentRoom() Returns `MRUKRoom` The current MRUKRoom based on the headset's position, or null if no rooms are available.
GetRooms ()	Get a list of all the rooms in the scene. Signature List< MRUKRoom > GetRooms() Returns `List< MRUKRoom >` A list of MRUKRoom objects representing all the rooms in the scene.
GetTrackables ( trackables )	Get all the trackables that have been detected so far. Signature void GetTrackables(List< MRUKTrackable > trackables) Parameters `trackables: List< MRUKTrackable >` The list to populate with the trackables. The list is cleared before adding any elements. Returns `void` Throws `ArgumentNullException` Thrown if trackables is `null`.
LoadSceneFromDevice ( requestSceneCaptureIfNoDataFound , removeMissingRooms , sceneModel )	Loads the scene from the data stored on the device. The user must have granted ScenePermissions or this will fail. In order to check if the user has granted permissions, call `Permission.HasUserAuthorizedPermission(OVRPermissionsRequester.ScenePermission)`. In order to request permissions from the user, call `Permission.RequestUserPermission(OVRPermissionsRequester.ScenePermission, callbacks)`. Signature async Task< LoadDeviceResult > LoadSceneFromDevice(bool requestSceneCaptureIfNoDataFound=true, bool removeMissingRooms=true, SceneModel sceneModel=SceneModel.V1) Parameters `requestSceneCaptureIfNoDataFound: bool` If true and no rooms are found when loading from device, the request space setup flow will be started. `removeMissingRooms: bool` When enabled, rooms that are already loaded but are not found in newSceneData will be removed. This is to support the case where a user deletes a room from their device and the change needs to be reflected in the app. `sceneModel: SceneModel` Select which scene model to load from the device. V2 corresponds to High Fidelity scene and captures more details of the room. Returns `async Task< LoadDeviceResult >` An enum indicating whether loading was successful or not.
LoadSceneFromJsonString ( jsonString , removeMissingRooms )	Loads the scene from a JSON string representing the scene data. Signature async Task< LoadDeviceResult > LoadSceneFromJsonString(string jsonString, bool removeMissingRooms=true) Parameters `jsonString: string` The JSON string containing the serialized scene data. `removeMissingRooms: bool` When enabled, rooms that are already loaded but are not found in JSON the string will be removed. Returns `async Task< LoadDeviceResult >` An enum indicating whether loading was successful or not.
LoadSceneFromPrefab ( scenePrefab , clearSceneFirst )	Simulates the creation of a scene in the Editor, using transforms and names from our prefab rooms. Signature async Task< LoadDeviceResult > LoadSceneFromPrefab(GameObject scenePrefab, bool clearSceneFirst=true) Parameters `scenePrefab: GameObject` The prefab GameObject representing the scene or a collection of rooms. `clearSceneFirst: bool` If true, clears the current scene before loading the new one. Returns `async Task< LoadDeviceResult >` An enum indicating whether loading was successful or not.
LoadSceneFromSharedRooms ( roomUuids , groupUuid , alignmentData , removeMissingRooms )	Loads the scene based on scene data previously shared with the user via MRUKRoom.ShareRoomAsync or ShareRoomsAsync. This function should be used in co-located multi-player experiences by "guest" clients that require scene data previously shared by the "host". Signature async Task< LoadDeviceResult > LoadSceneFromSharedRooms(IEnumerable< Guid > roomUuids, Guid groupUuid,(Guid alignmentRoomUuid, Pose floorWorldPoseOnHost)? alignmentData, bool removeMissingRooms=true) Parameters `roomUuids: IEnumerable< Guid >` An optional collection of room anchor UUIDs for which scene data will be loaded from the given group context. `roomUuids` can be null in which case all rooms from the group context will be loaded, it is the same as calling the LoadSceneFromSharedRooms overload that doesn't contain the `roomUuids` argument. It is more efficient for the host to filter the set of rooms when sharing instead of filtering the rooms on the guest when loading so in the majority of cases `roomUuids` should be `null`. `groupUuid: Guid` UUID of the group from which to load the shared rooms. `alignmentData: (Guid alignmentRoomUuid, Pose floorWorldPoseOnHost)?` Use this parameter to correctly align local and host coordinates when using co-location. `alignmentRoomUuid`: the UUID of the room used for alignment. `floorWorldPoseOnHost`: world-space pose of the FloorAnchor on the host device. Using 'null' will disable the alignment, causing the mismatch between the host and the guest. `removeMissingRooms: bool` When enabled, rooms that are already loaded but are not found in the shared group will be removed. This is to support the case where a user deletes a room from their device and the change needs to be reflected in the app. Returns `async Task< LoadDeviceResult >` An enum indicating whether loading was successful or not. Throws `ArgumentException` Thrown if groupUuid equals `Guid.Empty`. `ArgumentException` Thrown if alignmentData.alignmentRoomUuid equals `Guid.Empty`.
LoadSceneFromSharedRooms ( groupUuid , alignmentData , removeMissingRooms )	Loads the scene based on scene data previously shared with the user via MRUKRoom.ShareRoomAsync or ShareRoomsAsync. This function should be used in co-located multi-player experiences by "guest" clients that require scene data previously shared by the "host". Signature Task< LoadDeviceResult > LoadSceneFromSharedRooms(Guid groupUuid,(Guid alignmentRoomUuid, Pose floorWorldPoseOnHost)? alignmentData, bool removeMissingRooms=true) Parameters `groupUuid: Guid` UUID of the group from which to load the shared rooms. `alignmentData: (Guid alignmentRoomUuid, Pose floorWorldPoseOnHost)?` Use this parameter to correctly align local and host coordinates when using co-location. `alignmentRoomUuid`: the UUID of the room used for alignment. `floorWorldPoseOnHost`: world-space pose of the FloorAnchor on the host device. Using 'null' will disable the alignment, causing the mismatch between the host and the guest. `removeMissingRooms: bool` When enabled, rooms that are already loaded but are not found in the shared group will be removed. This is to support the case where a user deletes a room from their device and the change needs to be reflected in the app. Returns `Task< LoadDeviceResult >` An enum indicating whether loading was successful or not. Throws `ArgumentException` Thrown if groupUuid equals `Guid.Empty`. `ArgumentException` Thrown if alignmentData.alignmentRoomUuid equals `Guid.Empty`.
RegisterRoomCreatedCallback ( callback )	Register to receive a callback when a new room has been created from scene capture. Signature void RegisterRoomCreatedCallback(UnityAction< MRUKRoom > callback) Parameters `callback: UnityAction< MRUKRoom >` `MRUKRoom` The created room object. Returns `void`
RegisterRoomRemovedCallback ( callback )	Registers a callback function to be called before the room is removed. Signature void RegisterRoomRemovedCallback(UnityAction< MRUKRoom > callback) Parameters `callback: UnityAction< MRUKRoom >` The function to be called when the room is removed. It takes one parameter: `MRUKRoom` The removed room object. Returns `void`
RegisterRoomUpdatedCallback ( callback )	Register to receive a callback when a room has been updated from scene capture. Signature void RegisterRoomUpdatedCallback(UnityAction< MRUKRoom > callback) Parameters `callback: UnityAction< MRUKRoom >` `MRUKRoom` The updated room object. Returns `void`
RegisterSceneLoadedCallback ( callback )	Register to receive a callback when the scene is loaded. If the scene is already loaded at the time this is called, the callback will be invoked immediately. Callbacks are invoked in the order they were registered. This is important if there are dependencies between different components. For example, EffectMesh spawns colliders and another component may expect the colliders to already exist when it runs to perform physics checks. To ensure proper initialization order, register callbacks that create dependencies (like EffectMesh) before registering callbacks that depend on them. EffectMesh registers for the callback in Start(). If you have your own component that also needs to register in Start() and depends on EffectMesh, you must configure it with a higher execution order to ensure it registers after EffectMesh. For more information on script execution order, see the Unity documentation: https://docs.unity3d.com/Manual/class-MonoManager.html⁠ Signature void RegisterSceneLoadedCallback(UnityAction callback) Parameters `callback: UnityAction` The callback function to be invoked when the scene is loaded. Returns `void`
SaveSceneToJsonString ( coordinateSystem , includeGlobalMesh , rooms )	Serializes the scene data into a JSON string. The scene data includes rooms, anchors, and their associated properties. The method allows for the specification of the coordinate system (Unity or Unreal) and whether to include the global mesh data. Signature string SaveSceneToJsonString(SerializationHelpers.CoordinateSystem coordinateSystem=SerializationHelpers.CoordinateSystem.Unity, bool includeGlobalMesh=true, List< MRUKRoom > rooms=null) Parameters `coordinateSystem: SerializationHelpers.CoordinateSystem` The coordinate system to use for the serialization (Unity or Unreal). `includeGlobalMesh: bool` A boolean indicating whether to include the global mesh data in the serialization. Default is true. `rooms: List< MRUKRoom >` A list of rooms to serialize, if this is null then all rooms will be serialized. Returns `string` A JSON string representing the serialized scene data.
SaveSceneToJsonString ( includeGlobalMesh , rooms )	Serializes the scene data into a JSON string. The scene data includes rooms, anchors, and their associated properties. The method allows for the specification of the coordinate system (Unity or Unreal) and whether to include the global mesh data. Signature string SaveSceneToJsonString(bool includeGlobalMesh=true, List< MRUKRoom > rooms=null) Parameters `includeGlobalMesh: bool` A boolean indicating whether to include the global mesh data in the serialization. Default is true. `rooms: List< MRUKRoom >` A list of rooms to serialize, if this is null then all rooms will be serialized. Returns `string` A JSON string representing the serialized scene data.
SetCustomWorldLockAnchor ( anchor , poseOffset )	When set, world locking will use the anchor provided here instead of the computed default one. Revert to the default anchor by calling SetCustomWorldLockAnchor(null, Pose.identity). The tracking space will be shifted by poseOffset and then every frame will subsequently be shifted to compensate for drifting, ensuring that your virtual content stays locked to the real world IF the WorldLocking feature is enabled on MRUK. Signature void SetCustomWorldLockAnchor(OVRSpatialAnchor anchor, Pose poseOffset) Parameters `anchor: OVRSpatialAnchor` If set to null, will revert to default `poseOffset: Pose` The offset to apply in addition to what world locking applies Returns `void`
ShareRoomsAsync ( rooms , groupUuid )	Shares multiple MRUK rooms with a group. Note that there is a performance overhead in sharing more rooms than necessary. Consider sharing only the current room using GetCurrentRoom and MRUKRoom.ShareRoomAsync. Signature async OVRTask< OVRResult< OVRAnchor.ShareResult > > ShareRoomsAsync(IEnumerable< MRUKRoom > rooms, Guid groupUuid) Parameters `rooms: IEnumerable< MRUKRoom >` A collection of rooms to be shared. `groupUuid: Guid` UUID of the group to which the room should be shared. Returns `async OVRTask< OVRResult< OVRAnchor.ShareResult > >` A task that tracks the asynchronous operation. Throws `ArgumentNullException` Thrown if rooms is `null`. `ArgumentException` Thrown if groupUuid equals `Guid.Empty`.

Static Methods

HasSceneModel ()

Checks whether any anchors can be loaded.

Signature

static async Task< bool > HasSceneModel()

Returns

async Task< bool > Returns a task-based bool, which is true if there are any scene anchors in the system, and false otherwise. If false is returned, then either the scene permission needs to be set, or the user has to run Scene Capture.

Inner Class

MRUKSettings Class

Represents the settings for the <see cref"MRUK"/> instance, including data source configurations, startup behaviors, and other scene related settings.

These settings are serialized and can be modified in the Unity Editor from the <see cref"MRUK"/> component.

Fields

DataSource : SceneDataSource	Where to load the data from. Signature SceneDataSource DataSource
EnableHighFidelityScene : bool	High Fidelity scene supports multiple floors, slanted ceilings, and inner walls. This property only applies to Load Scene On Startup. When calling LoadSceneFromDevice() directly, you can choose the scene model on a per call basis. At the moment scene sharing is not supported for High Fidelity scene. Signature bool EnableHighFidelityScene
LoadSceneOnStartup : bool	Trigger a scene load on startup. If set to false, you can call LoadSceneFromDevice(), LoadScene or LoadSceneFromJsonString() manually. Signature bool LoadSceneOnStartup
RoomIndex : int	The index (0-based) into the RoomPrefabs or SceneJsons array determining which room to load. -1 is random. Signature int RoomIndex
RoomPrefabs : GameObject[]	The list of prefab rooms to use. when <see cref"SceneDataSource"/> is set to Prefab or DeviceWithPrefabFallback. The MR Utilty kit package includes a few sample rooms to use as a starting point for your own scene. These rooms can be modified in the Unity editor and then saved as a new prefab. Signature GameObject [] RoomPrefabs
SceneJsons : TextAsset[]	The list of JSON text files with scene data to use when <see cref"SceneDataSource"/> is set to JSON or DeviceWithJSONFallback. The MR Utilty kit package includes a few serialized sample rooms to use as a starting point for your own scene. Signature TextAsset [] SceneJsons
SeatWidth : float	The width of a seat. Used to calculate seat positions with the COUCH label. Default is 0.6f. Signature float SeatWidth

Properties

TrackableAdded : UnityEvent< MRUKTrackable > [Get]	Invoked when a newly detected trackable has been localized. When a new OVRAnchor has been detected and localized, a new `GameObject` with a MRUKTrackable is created to represent it. Its transform is set, and then this event is invoked. Subscribe to this event to add additional child GameObjects or further customize the behavior. This example shows how to create a MonoBehaviour that instantiates a custom prefab: class MyCustomManager : MonoBehaviour { public GameObject Prefab; public void OnTrackableAdded(MRUKTrackable trackable) { Instantiate(Prefab, trackable.transform); } } Signature UnityEvent<MRUKTrackable> TrackableAdded
TrackableRemoved : UnityEvent< MRUKTrackable > [Get]	Invoked when an existing trackable is no longer detected by the runtime. When an anchor is removed, no action is taken by default. The MRUKTrackable, if any, is not destroyed or deactivated. Subscribe to this event to change this behavior. Once this event has been invoked, the MRUKTrackable's anchor (MRUKTrackable.Anchor) is no longer valid. Signature UnityEvent<MRUKTrackable> TrackableRemoved
TrackerConfiguration : OVRAnchor.TrackerConfiguration [Get][Set]	The requested configuration of the tracking service. This property represents the requested tracker configuration (which types of trackables to track). It is possible that some configuration settings may not be satisfied (for example, due to lack of device support). MRUK.TrackerConfiguration represents the true state of the system. Signature OVRAnchor.TrackerConfiguration TrackerConfiguration

Inner Enums

PositioningMethod Enum

When interacting specifically with tops of volumes, this can be used to specify where the return position should be aligned on the surface e.g.

some apps might want a position right in the center of the table (chess) for others, the edge may be more important (piano or pong)

Enumeration Constants

Member
DEFAULT
CENTER
EDGE

SceneDataSource Enum

Specify the source of the scene data.

Enumeration Constants

Member	Description
Device	Load scene data from the device.
Prefab	Load scene data from prefabs.
DeviceWithPrefabFallback	First try to load data from the device and if none can be found fall back to loading from a prefab.
Json	Load Scene from a Json file.
DeviceWithJsonFallback	First try to load data from the device and if none can be found fall back to loading from a Json file.

RoomFilter Enum

Specifies the filtering options for selecting rooms within the scene data.

Enumeration Constants

Member
None
CurrentRoomOnly
AllRooms

LoadDeviceResult Enum

Return value from the call to LoadSceneFromDevice.

This is used to indicate if the scene was loaded successfully or if there was an error.

Enumeration Constants

Member	Value	Description
Success	OVRAnchor.FetchResult.Success	Scene data loaded successfully.
NoScenePermission	1	User did not grant scene permissions.
NoRoomsFound	2	No rooms were found (e.g. User did not go through space setup)
DiscoveryOngoing	3	Only one discovery can happen at a time.
Failure	OVRPlugin.Result.Failure	Generic failure.
StorageAtCapacity	OVRPlugin.Result.Failure_SpaceStorageAtCapacity	Storage at capacity.
NotInitialized	OVRPlugin.Result.Failure_NotInitialized	Not initialized (this can happen when running in the editor without Link)
FailureDataIsInvalid	OVRAnchor.FetchResult.FailureDataIsInvalid	Invalid data.
FailureInsufficientResources	OVRAnchor.FetchResult.FailureInsufficientResources	Resource limitation prevented this operation from executing. Recommend retrying, perhaps after a short delay and/or reducing memory consumption.
FailureInsufficientView	OVRAnchor.FetchResult.FailureInsufficientView	Insufficient view. The user needs to look around the environment more for anchor tracking to function.
FailurePermissionInsufficient	OVRAnchor.FetchResult.FailurePermissionInsufficient	Insufficient permission. Recommend confirming the status of the required permissions needed for using anchor APIs.
FailureRateLimited	OVRAnchor.FetchResult.FailureRateLimited	Operation canceled due to rate limiting. Recommend retrying after a short delay.
FailureTooDark	OVRAnchor.FetchResult.FailureTooDark	Too dark. The environment is too dark to load the anchor.
FailureTooBright	OVRAnchor.FetchResult.FailureTooBright	Too bright. The environment is too bright to load the anchor.

SurfaceType Enum

Defines flags for different types of surfaces that can be identified or used within a scene.

This is mainly used when querying for specifin anchors' surfaces, finding random positions, or ray casting.

Enumeration Constants

Member	Value
FACING_UP	1 << 0
FACING_DOWN	1 << 1
VERTICAL	1 << 2

SceneModel Enum

Enum to specify which scene model to load.

Enumeration Constants

Member	Description
V1	The original simple scene where each room contains a single horizontal floor and ceiling.
V2	The High Fidelity scene model which can contain multiple floors and ceilings at different heights. Slanted ceilings and inner wall faces to represent pillars for example.
V2FallbackV1	When used for loading it will first try to load the v2 scene and if it is not found it will fall back to loading v1.