Meta Developers

By default, a loading screen (a splash image, “3 dots”) is shown with a black background. For MR apps that launch directly into a passthrough view, the user experience is typically much better if the loading screen shows passthrough in the background. This topic describes the steps and options for achieving seamless passthrough during the transition from the system home to your app.

Overview

To benefit from seamless passthrough while your app is launching, do the following:

Avoid using a auto-loading engine splash screen. Use a combination of a system splash screen and custom startup levels instead. You can use either, both or none, depending on what is the right experience for you app.
Set your System Splash Screen Background to Passthrough (Contextual).

Best Practices

Before you start implementing the splash screen in your app, read the best practices outlined in the Splash Screen Best Practices guide.

Loading Screen Types

You can choose between several different options of loading experiences for your app:

Auto-loading engine splash screen are displayed by the app once it has loaded.
- Auto-loading engine splash screen cannot be configured to show passthrough in the background. If your app is currently using this feature, please migrate to using system splash screen or a custom startup level (see below).
- Do the following to disable the auto-loading engine splash screen:
  - Go to Project Settings > Plugins > Meta XR.
  - Ensure that Auto Enabled is not checked and Splash Descs is empty.
System splash screen is displayed by the Meta Horizon OS while the app is loading and not yet rendering. By default, a loading indicator with 3 grey dots is shown, but you can specify a custom splash image to be displayed. See System Splash Screen for instructions.
- The system splash screen is limited to showing a single static 2D or stereoscopic logo while the app is loading.
- The splash screen is shown for as long as it takes for your app to start rendering. There is no direct control over the display duration.
- You can configure the background of the system splash screen to show passthrough conditionally. See next section.
Custom startup levels are referring to regular Unreal levels that you can add to your projects to extend the loading/onboarding experience.
- You have full control over the experience, including logos, 3D geometry, animations, sound effects, etc.
- You can have full control over passthrough using the same means as you would normally add passthrough to your app.

Configuring System Splash Screen

To configure the background of the system splash screen, do the following:

Go to Project Settings > Plugins > Meta XR.
Adjust System Splash Screen Background. You have the following options:
- Black: the system splash screen is always displayed against black background. Not recommended for MR apps.
- Passthrough (Contextual): the system splash screen is displayed against passthrough background if passthrough is enabled in the user’s home environment. Otherwise, it is still displayed against black background.

This setting takes effect regardless of whether a splash image is specified in System Splash Screen. If no splash image is specified, it affects the background of the “3 dots” loading indicator.

Setting the Background Manually

If you’re using v59 or earlier of the Oculus SDK, the aforementioned option System Splash Screen Background won’t be available. You can still enable passthrough background by manually adding a node to AndroidManifest.xml:

Go to Project Settings > Platforms > Android.
Locate the Advanced APK Packaging section.
In Extra Settings for <application> section, add the following (use \n to separate it from existing lines):

<meta-data android:name="com.oculus.ossplash.background" android:value="passthrough-contextual"/>

Add a Custom Startup Level

When adding a custom startup level, ensure that the level contains an underlay passthrough layer (see Getting Started with Passthrough) that is enabled from the start and visible throughout the level. The level can display any elements that should be visible on top of passthrough, for example logos, loading animations, etc.

You can use the system recommendation (see Enable Based on System Recommendation) to show the passthrough background only if the user has enabled passthrough in the system.

Did you find this page helpful?