Develop

Importing Scene Entity Meshes (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

Note: If you are using MR Utility Kit, mesh orientation requirements are handled automatically. The requirements below apply only to legacy Scene Actor projects. For migration guidance, see Migrate to MR Utility Kit.

When using the Scene Actor it is essential to properly orient and position meshes if you will use them to represent scene entities. Refer to the Scene sample to see how you should lay out scene entity meshes.

Unreal can modify the orientations and translations of imported meshes. See Epic’s Importing Static Meshes⁠ guide (UE 4.27; search dev.epicgames.com for the equivalent page in later versions). You can use this functionality instead of manually reauthoring mesh assets.

Bounded 2D Meshes

Bounded 2D meshes must be planar (no depth), oriented along the YZ plane with the normal of the plane facing the -X-axis, and centered at the origin.

Wall mesh from perspective projection showing the planar face normal pointing towards negative X.

Scene sample’s Wall mesh from a perspective projection. The planar face’s normal points towards -X.

Wall mesh from back orthographic projection showing the origin at the center of the plane face.

Scene sample’s Wall mesh from a back orthographic projection. The mesh’s origin is at the center of the plane’s face.

Bounded 3D Meshes

The origin must be at the top of the mesh. In addition, the mesh should be facing the XY plane. For example, using the engine’s “SM_MatPreviewMesh_01” asset:

If you are going to use this mesh with Scene, you must import it like so:

Scene sample’s Bounded 3D mesh from a perspective projection. The mesh is oriented to face the XY plane.

Scene sample’s Bounded 3D mesh from a bottom orthographic projection. The origin is at the top of the mesh.

Note: The scale of the imported mesh is irrelevant. The Scene Actor will properly rescale the spawned scene entity actors, so their sizes match their physical representations.

Configuring the Behavior of the Scene Actor

The Scene Actor exposes various other settings that dictate its behavior.

Behavioral default settings of the Scene Actor:

Launch Scene Capture when Missing Scene: This determines whether the system should automatically launch Scene Capture when a captured Scene Model is not detected. You can set this setting to “never,” “once,” or “always.”

Max Queries: The maximum number of queries you can make when checking for captured scene entities.

Populate Scene on Begin Play: Whether the Scene Actor should try to populate the scene when you call its BeginPlay() function.

Notes

At the moment, the user can only clear an active Scene Model by resetting the boundary through Settings > Physical Space > Space Setup on the headset.

Anytime the Scene Actor launches Scene Capture, the system will attempt to populate the Scene Actor once you exit Scene Capture to return to the Unreal application.

Note: The “Ensure Room Is Valid” setting shown in the second flowchart below has been removed from the Scene Actor source code. The first flowchart reflects current behavior, controlled solely by the “Launch Scene Capture when Missing Scene” setting.

Unless “Launch Scene Capture when Missing Scene” is set to “never,” this setting dictates when the system will automatically launch Scene Capture.

The following diagram shows the current logical flow, where Scene Capture launch is controlled solely by the “Launch Scene Capture when Missing Scene” setting: