Develop

Migrate to MR Utility Kit

Updated: Apr 13, 2026

This page helps you migrate existing apps from AOculusXRSceneActor to Mixed Reality Utility Kit (MRUK). It focuses on the differences between the two systems. If you are starting a new project, refer to the MR Utility Kit documentation.

Deprecated

AOculusXRSceneActor and its associated classes are deprecated since v65. Use MR Utility Kit instead for all new and existing projects.

Before migrating, ensure MR Utility Kit is installed and enabled in your project. See the MR Utility Kit getting started guide for setup instructions.

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 actor spawner is optional. If you only want to load the scene model and use it for other purposes, 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.

The following example shows the difference in C++:

Old approach:

// AOculusXRSceneActor automatically loads on BeginPlay
// via bPopulateSceneOnBeginPlay = true
// No completion callback available

New approach:

UMRUKSubsystem* Subsystem = GetGameInstance()->GetSubsystem<UMRUKSubsystem>();
Subsystem->OnSceneLoaded.AddDynamic(this, &AMyActor::OnSceneLoaded);
Subsystem->LoadSceneFromDevice();

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 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.

MRUK supports creating a procedural mesh if no actor is specified, which is useful in cases where you want a mesh that exactly matches the volume or plane.

AMRUKAnchorActorSpawner has a CutHoleLabels property that automatically cuts holes in wall meshes for doors and windows. By default, this includes WindowFrame, DoorFrame, and Opening labels.

Capture Flow

AOculusXRSceneActor had a LaunchCaptureFlow() method and a LaunchCaptureFlowWhenMissingScene property to trigger Space Setup when no scene data was available. In MRUK, use UMRUKSubsystem::LaunchSceneCapture() to launch the capture flow. Subscribe to the OnCaptureComplete delegate on UMRUKSubsystem to receive a notification when the capture finishes. The delegate provides a boolean indicating whether the capture succeeded.

Events and Callbacks

The old AOculusXRSceneActor system used implicit callbacks that ran during scene population. MRUK provides explicit BlueprintAssignable delegates on UMRUKSubsystem for finer control:

OnSceneLoaded: Fires when scene data has been loaded. Provides a boolean indicating success.

OnRoomCreated: Fires after a new AMRUKRoom is created. Provides a pointer to the room.

OnRoomUpdated: Fires after an existing AMRUKRoom is updated. Provides a pointer to the room.

OnRoomRemoved: Fires when an AMRUKRoom is removed. Provides a pointer to the room.

OnCaptureComplete: Fires after the capture flow finishes. Provides a boolean indicating success.

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. For more details, see World locking in the MR Utility Kit Features documentation.

Scene Mesh

AOculusXRSceneActor allows you to configure how it loads via the UOculusXRSceneGlobalMeshComponent. 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. Call GenerateProceduralSceneMesh on the AMRUKRoom class to generate a procedural mesh from the global mesh anchor data. This method accepts a UMaterialInterface parameter for the material to apply to the generated mesh.

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.

MRUK supports multiple simultaneous rooms. The Rooms property is a TArray of AMRUKRoom pointers, and AMRUKAnchorActorSpawner offers a SpawnMode setting with CurrentRoomOnly and AllRooms options for controlling which rooms receive spawned actors.

Next Steps

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