This page will help you migrate existing apps from OculusXRSceneActor to MR Utility Kit, it focuses on the differences between them. If you are starting a new project, refer to the MR Utility Kit documentation.

Getting started

AOculusXRSceneActor is responsible for both loading the scene model and spawning actors to represent the scene anchors. In MRUK, these two responsibilities are split between UMRUKSubsystem and AMRUKAnchorActorSpawner. The subsystem loads the scene model while the actor spawner is responsible for spawning actors to represent them. The latter is optional. if you just want to load the scene model, and use it for other purposes, then you don’t need an actor spawner.

Loading the Scene

AOculusXRSceneActor has a property bPopulateSceneOnBeginPlay which defaults to true to load the scene. This has the downside that there is no easy way to know when the scene is fully loaded. In MRUK you can use the LoadSceneFromDeviceAsync blueprint node, which will complete asynchronously once the scene data is fully loaded.

Spawning Actors

AOculusXRSceneActor has ScenePlaneSpawnedSceneAnchorProperties and SceneVolumeSpawnedSceneAnchorProperties properties that map anchor labels to actor components and static meshes. With MRUK, similarly AMRUKAnchorActorSpawner has a SpawnGroups property which maps anchor labels to actors. The main differences between these are:

With AOculusXRSceneActor you specify an actor component and mesh. With MRUK, you just specify an actor. Typically, you will want to use a Blueprint Class in MRUK, which gives you much more flexibility.

There is a single map of label to actor in MRUK. It is not split between planes and volumes.

AOculusXRSceneActor has a very particular set of requirements for importing meshes. In MRUK, the process is straightforward. The origin may be anywhere, and actors should have the Z axis pointing upwards, as is standard in the Unreal engine. This typically means you can use any existing assets without modification, and use them directly with AMRUKAnchorActorSpawner. Additionally, MRUK supports creating a procedural mesh if no actor is specified which is useful in cases where you just want a mesh that exactly matches the volume or plane.

World Locking

Unlike UOculusXRSceneAnchorComponent, the anchors in MRUK do not move in Unreal coordinate space once they have been created. This makes keeping content synchronized with the real world easier. See the World locking section in the documentation here for more details.

Scene Mesh

OculusXRSceneActor allows you to configure how it loads via the OculusXRSceneGlobalMesh component. In MRUK, the mesh is attached to AMRUKAnchor, which is accessible via the GlobalMeshAnchor property on the AMRUKRoom class. Since the mesh is large, it is not loaded by default along with the rest of the scene model. You must explicitly call LoadGlobalMesh on the AMRUKRoom class in order to load it.

Accessing the Scene Data Hierarchy

AOculusXRSceneActor has the function GetActorsBySemanticLabel which can be used to access the actors. In MRUK, the anchors are accessible via the AllAnchors property on the AMRUKRoom class, and the rooms are accessible via the Rooms property on the UMRUKSubsystem class. This additional hierarchy ensures that MRUK’s API is ready to support multiple rooms.

Next Steps

The items listed here mainly bring you up to parity with OculusXRSceneActor. To see all the extra functionality MRUK offers, refer to the MR Utility Kit documentation.

Did you find this page helpful?