Develop

Add a splash screen

Updated: Oct 9, 2026

Overview

The Meta XR Core SDK lets the operating system show your image as a splash screen while your app loads. This page shows how to select the image in Unity, show a different image to each eye (stereo), choose the background, and size the image.

Prerequisites

  • A Unity project with the Meta XR Core SDK and an OVRCameraRig in the scene.
  • An image for the splash screen. For design guidance, see Splash screen best practices.
  • A Meta VR device to run your app on.

Steps

1. Import the splash image

Import your image into the Assets folder of your project. The System Splash Screen field accepts only assets from your project.
To choose the image dimensions, see Size the splash screen image. For a stereo splash screen, the image must be double-wide. Step 4 describes the layout.

2. Open the splash screen settings

  • In Hierarchy, select OVRCameraRig.
  • In Inspector, find the OVR Manager component.
  • Select the Quest tab.
  • Expand Quest Features.
  • Select the General tab.
The System Splash Screen, System Splash Screen Type, and System Splash Screen Background settings appear in that order.

3. Select the splash screen image

In System Splash Screen, click Select and choose your image.
System Splash Screen setting in the Quest Features section of the OVR Manager component
A System Splash Screen Texture dialog asks whether to save a compatible copy of the image. Choose one option:
  • Save and use copy: Opens a save dialog. Confirm the save to store a compatible PNG copy in your project and use it. The default name is OculusSystemSplashScreen.png. Save the copy inside your project’s Assets folder, which is the default folder. This option accepts any texture that Unity can import.
  • Use original: Uses your image as is. The image must be a PNG file.
If you are not sure which to choose, choose Save and use copy.
The System Splash Screen field shows the image Unity will use. If you chose Save and use copy, it shows the saved PNG copy. If you cancel the save dialog, the field keeps your original image, and the build fails if that image is not a PNG file.

4. (Optional) Make the splash screen stereo

By default, the system shows the same image to both eyes (Mono). To show a different view to each eye, use a double-wide image in steps 1 and 3, and then set System Splash Screen Type to Stereo.
A stereo image is one double-wide image:
  • The left eye sees the left half of the image.
  • The right eye sees the right half.
  • Both halves have the same width, so split the image exactly down the middle.
For example, a 2048 by 1024 image has two 1024 by 1024 halves.
Keep each half within the shape limit in Size the splash screen image.

5. (Optional) Set the background

In System Splash Screen Background, choose one option:
  • Black: The default.
  • Passthrough (Contextual): Shows passthrough as the background when passthrough is showing at the moment your app launches, and black otherwise.
While Passthrough Support, on the same General tab, is set to anything other than None, this field is read-only. Unity sets it to Passthrough (Contextual) when you enable Passthrough Support. To choose Black, set Passthrough Support to None. For details about passthrough backgrounds, see Passthrough loading screen.

6. Build and run your app

Build your app and run it on your device. The system shows your image as the splash screen while the app loads.

What Unity adds to your manifest

At build time, Unity adds these entries to your app’s Android manifest and copies the image into the APK as assets/vr_splash.png. You do not edit the manifest yourself. For a stereo splash screen with a black background and the default Color Gamut, the manifest includes these entries. The ... stands for the other attributes of your <application> element.
<application ...>
  <meta-data android:name="com.oculus.ossplash" android:value="true"/>
  <meta-data android:name="com.oculus.ossplash.type" android:value="stereo"/>
  <meta-data android:name="com.oculus.ossplash.colorspace" android:value="P3"/>
  <meta-data android:name="com.oculus.ossplash.background" android:value="black"/>
</application>
Unity writes com.oculus.ossplash.colorspace whenever a splash image is set. Its value follows the Color Gamut setting in the Performance & Quality section of the OVR Manager component, and is P3 in a new project.
For the values of com.oculus.ossplash, com.oculus.ossplash.type, and com.oculus.ossplash.background, see Add a splash screen (native).

Size the splash screen image

The system scales the splash screen to fit a fixed area in front of the user. The aspect ratio of your image, not its resolution, determines the displayed size. A higher-resolution image does not appear larger. It looks sharper up to the display’s pixel density. Past that density, extra resolution adds no sharpness and can cause aliasing. The system keeps the image’s proportions and does not crop or stretch it.
For a stereo splash screen, each eye sees one half of the image, so the system sizes the splash screen by the shape of one half. For example, a 2048 by 1024 stereo image and a 1024 by 1024 mono image appear at the same size, because each eye sees a square image. Keep each half no more than 2.3 times as wide as it is tall. Wider stereo images can display smaller than one half of the image would as a mono splash screen.

Splash screen behavior

The splash screen stays where it first appeared in front of the user and does not follow head movement. If the user recenters the view, the splash screen moves in front of the user again. It fades out once your app starts.
If you set a virtual reality splash image in Unity’s Player Settings, it appears after the system splash screen.

Troubleshooting

The build fails with an invalid file format error

Symptom: The build fails with a message that starts with “Invalid file format of System Splash Screen. It has to be a PNG file to be used by the Quest OS.”
Solution: The selected image is not a PNG file. Select the image again and choose Save and use copy to use a compatible PNG copy. Or choose a PNG file and select Use original.

The splash screen does not appear

Symptom: Your app loads on the device without a splash screen.
Solution: Check that the System Splash Screen field shows your image. If it is empty, select your image as described in step 3. Then build and run your app on the device again.

The splash screen settings are not visible

Symptom: You select OVRCameraRig, but System Splash Screen does not appear in Inspector.
Solution: Quest Features is collapsed by default, and the splash screen settings are on its General tab. In the OVR Manager component, select the Quest tab, expand Quest Features, and then select the General tab.

Each eye shows the whole side-by-side image

Symptom: Both eyes see the full image, with the left and right halves next to each other.
Solution: In the OVR Manager component, set System Splash Screen Type to Stereo.

The stereo splash screen looks smaller than expected

Symptom: A stereo splash screen displays smaller than one half of the image shown as a mono splash screen.
Solution: Check the shape of one half of your image. When one half is more than 2.3 times as wide as it is tall, the splash screen can display smaller. Change the image so each half is no more than 2.3 times as wide as it is tall.

The splash screen looks blurry

Symptom: The splash screen appears soft or pixelated.
Solution: Select an image with a higher resolution and the same aspect ratio. For a stereo image, increase the resolution of both halves. A higher-resolution image looks sharper up to the display’s pixel density, and the displayed size does not change. Past that density, extra resolution adds no sharpness and can cause aliasing.

A second splash screen appears after the system splash screen

Symptom: Your app shows another splash screen after the system splash screen.
Solution: Check Unity’s Player Settings for a virtual reality splash image. Unity shows it after the system splash screen. To remove it, clear that setting.
Meta
English (US)
© 2026 Meta