Develop

Scene API Getting Started with Scene Actor (deprecated)

Updated: Apr 14, 2026

OculusXRSceneActor Deprecation

OculusXRSceneActor is deprecated. New features will be delivered through MR Utility Kit.

Refer to the following as guidance on which APIs to use:

New projects:

Use MR Utility Kit for new development

Existing projects:

To access the latest features, migrate your existing projects to MR Utility Kit.

If you don’t require the latest features or tools provided by MR Utility Kit, continue using OculusXRSceneActor

Introduction

Before you begin with Scene, make sure to use the latest version of Meta Horizon OS on your Meta Quest device and the Meta XR Plugin in your Unreal project. Scene functionality is supported on Meta Quest devices. Do the following:

Ensure the headset is connected to the internet and has the latest version of Meta Horizon OS installed. To verify the latest version, in the headset, go to Settings > System > Software Update.

Set up your Unreal project with the Meta XR Plugin by following the steps in the getting started guide.

Setting Up the Project

Open Edit > Project Settings > (in Plugins section) > Meta XR.

In the General section, go to the XR API list, and then select Epic Native OpenXR (Recommended).

In the Mobile section, select Passthrough Enabled, Scene Support and Anchor Support.

Follow the typical steps for adding a Passthrough Layer to an Unreal project.

Meta XR project settings showing Scene Support and Anchor Support enabled

You can use the Scene Actor as any other type of actor in Unreal. The easiest way to start experimenting with the Scene Actor is to place it on a level within the editor. From the “Place Actors” panel, search for the “Oculus XR Scene Actor” class and drag-drop it anywhere on your level.

Spawned Scene Entities Properties

Within Scene Capture (the headset’s room setup process), you may create two types of entities: ScenePlane and SceneVolume entities.

ScenePlane: These planar entities do not have a depth component.

SceneVolume: These entities include a volume.

For example, a captured room layout will have its walls, floor, and ceiling represented as ScenePlane entities. For more details about the various types of scene entities you can capture within Scene Capture, refer to the supported semantic labels page.

Within the editor, looking at the details panel for Scene Actors, two maps can be found representing the properties of ScenePlane and SceneVolume entities that you will spawn. Each map entry is keyed by the semantic label associated with a captured scene entity. The maps can be modified to add or remove entries; removing a label causes the corresponding entity type to be ignored at runtime. These maps dictate the scene entities that will make up the final Scene Model, which is the runtime representation of your captured room.

By default, the Scene Actor will populate properties for the following scene entities:

ScenePlane

WALL_FACE

CEILING

FLOOR

COUCH

TABLE

DOOR_FRAME

WINDOW_FRAME

WALL_ART

INVISIBLE_WALL_FACE

OTHER

SceneVolume

COUCH

TABLE

SCREEN

BED

LAMP

PLANT

STORAGE

OTHER

For the complete list of supported labels, see Supported semantic labels.

The map’s member values provide various settings that dictate how you will spawn a scene entity. For example, you will see three properties if you expand one of the map’s members:

Actor Component: The spawned actor will have an actor component that will update the actor’s pose based on the position of the related scene entity in the physical space. This actor component must either be or derive from the UOculusXRSceneAnchorComponent class type.

Static Mesh: The spawned actor will be a static mesh actor. The static mesh you define in this property will be set to the spawned static mesh actor.

Force Parallel to Floor (deprecated): This property is deprecated. Alignment is now done automatically at a lower level. Previously, enabling this property caused the system to adjust the transformation (based on the scene entity’s pose) to ensure that the actor remained parallel to the ground/floor.

Restrictions

The deprecated Scene Actor API does not support Play In Editor (PIE) or Meta Quest Link. Scene logic using this API will only work when running the application on the Meta Quest device.

For Scene testing outside the device, the Meta XR Simulator supports Scene information through synthetic environments, and MR Utility Kit provides LoadSceneFromJsonAsync for in-editor iteration. For migration instructions, see Migrate to MR Utility Kit.