Meta Developers

Since there have been fundamental changes to underlying technology, there is no direct upgrade path from legacy Oculus Avatars to Meta Avatars. However it is possible for an application to support both Avatar systems.

Prerequisites

Unity Editor 2022.3.15f1 or higher (Unity 6+ is recommended)
A Unity project
If you have not already created a Unity project, see Set up Unity for XR development for instructions on creating one.

Configuring your project

To configure a project for Meta Avatars, follow these steps:

Enable VR support from the Meta XR plug-in.
Use XR Plugin Management (Go to Edit > Project Settings…) to verify that Oculus is checked.
Apply recommended Unity Settings to optimize the app performance and quality. Specially, make sure to set up the Color Space property to Linear under the Android platform.

Importing the Meta Avatars SDK to your project

There are two ways to import the latest Meta Avatars SDK in the Unity project; from the Unity Asset Store or from the Downloads page. If you’re using any prior version of the Meta Avatars SDK in your existing project and you want to upgrade to the latest SDK without creating a new project, go to Upgrading to Latest SDK section.

Import the SDK from Unity Asset Store

Go to the Downloads page and then click Download from Unity Asset Store.
Once in the Unity Asset Store, log in if needed.
Click the Add to My Assets button.
Select Open in Unity to start the integration process with the Package Manager in Unity. If asked, allow Asset Store links to be opened by Unity.
The Unity Package Manager window will open.
On the “Meta Avatars SDK” panel, click Install.
If prompted to restart Unity, click Restart Editor.
[Optional] Import Samples: In Unity select Window > Package Manager > Packages: In Project > Meta Avatars SDK > Samples > Import

Import the SDK from Meta Quest Developer Center

Go to the Downloads page.
Click on the three dots next to Download from Unity and then click Download from Meta.
Search for com.meta.xr.sdk.avatars.sample.avatars and download the desired version.
In Unity select Window > Package Manager > + > Add package from tarball and select com.meta.xr.sdk.avatars.sample.assets-XX.X.X.tgz. The sample assets package much be installed first before installing the avatar sdk package.
Search for com.meta.xr.sdk.avatars and download the desired version.
In Unity select Window > Package Manager > + > Add package from tarball and select com.meta.xr.sdk.avatars-XX.X.X.tgz
If prompted to restart Unity, click Restart Editor.
[Optional] Import Samples: In Unity select Window > Package Manager > Packages: In Project > Meta Avatars SDK > Samples > Import

Once imported, use the Project Setup Tool to review outstanding issues and recommended items on your project (on the Android tab). This will help you to go through the necessary fixes so you can start developing more quickly.

Upgrading an existing project to the latest Meta Avatars SDK version

You can upgrade prior versions of the Meta Avatars SDK to the latest version by using the following process:

Close Unity, if it’s open.
On your computer, go to the folder where you’ve saved the project. For example, /username/sample-project/.
In your project, open the Assets folder, and then delete the Oculus folder.
Search for and remove files starting with Oculus and OVR within your project. In addition, if you’re building an Android app, search for filenames starting or matching with AndroidManifest, vrapi, vrlib, and vrplatlib. These files are usually located in different folders of your project, so search by the filename and then remove them.
Open the project in which you want to upgrade the package.
Follow above steps on importing the Meta Avatars SDK

Testing Meta Avatars SDK integration

You can verify your Meta Avatars integration by playing the Samples/Meta Avatars SDK/XX.X.X/Sample Scenes/Scenes/MirrorScene/MirrorScene.unity sample scene.

Troubleshooting

Multiple precompiled assemblies

This issue is caused by multiple precompiled assemblies with the same name.

Resolution: You might need to remove any of the duplicated precompiled assemblies (e.g. Unchecking Newtonsoft.Json.dll when importing Meta Avatars SDK).

Unable to start XR Plugin

Possible causes include a headset not being attached, or the Oculus runtime is not installed or up to date.

Resolution:

Make sure that your headset is connected and in developer mode.
Verify that the XR Plugin is installed, Oculus is checked in the Plug-in Providers and also XR is initialized on startup. Use XR Plugin Management (Go to Edit > Project Settings…) to review those settings.

Unable to load Avatar

You are having errors in the console or just the avatar is not showing up while testing with the MirrorScene.

Resolution: Please refer to Loading Avatars Common Errors section for guidance.

Did you find this page helpful?