Building and using XR Player on Meta Quest 3

This guide covers compiling the XR player sample Unity project for Meta Quest 3 and configuring it with specific glTF content.

This section assumes adb is installed on the machine, and a Meta Quest 3 with developer options and USB debugging enabled is connected.

The project requires Unity 3D 2022.3.34f1 with both Android and iOS support modules installed. Note that Android API 28 and NDK 27.2.12479018 are used.

While this guide assumes a Windows environment with a git-bash terminal (eg. to run shell scripts), the same instructions apply to other platoforms.

The tutorial covers the following steps:

  1. Clone the XR Player unity project
  2. Compile & install media pipeline library and plugins for Android
  3. Build and run the unity project
  4. Configure the XR player sample application
  5. Launch the player

Step 1: Clone the XR Unity Player project 

git clone --recursive https://github.com/5G-MAG/rt-xr-unity-player.git

Note: –recursive is required to get all submodules checked out.

Step 2: Build and install media pipelines

Clone and install the source code 

git clone https://github.com/5G-MAG/rt-xr-maf-native.git
cd rt-xr-maf-native

Compile the MAF library and media pipeline plugins

Compile and install dependencies

Follow these instructions to compile the avpipeline dependencies.

Copy the generated libraries into the avpipeline subproject:

mkdir -p ./rt-xr-maf-native/subprojects/avpipeline/external/avcodec/android/arm64-v8a/lib
cp ./rt-common-shared/avcodec-build/build/ffmpeg/aarch64/lib/*.so ./rt-xr-maf-native/subprojects/avpipeline/external/avcodec/android/arm64-v8a/lib

cp -r ./rt-common-shared/avcodec-build/build/ffmpeg/aarch64/include ./rt-xr-maf-native/subprojects/avpipeline/external/avcodec/android/arm64-v8a/include/

cp ./rt-common-shared/avcodec-build/build/ffmpeg/aarch64/LICENSE ./rt-xr-maf-native/subprojects/avpipeline/external/avcodec/android/arm64-v8a/LICENSE

Configure cross compilation configuration

  • Download and install the Android NDK. In the next steps, we assume a Windows x86_64 environment with the Android NDK 27.2.12479018 installed in C:\Users\<your_user_name>\AppData\Local\Android\Sdk\ndk.
  • Locate the ./rt-xr-maf-native/crossfile/android-arm64-v8a and modify it to point to your local NDK installation, for instance:
[binaries]
ar = ['C:\Users\<your_user_name>\AppData\Local\Android\Sdk\ndk\27.2.12479018\toolchains\llvm\prebuilt\windows-x86_64\bin\llvm-ar']
c = ['C:\Users\<your_user_name>\AppData\Local\Android\Sdk\ndk\27.2.12479018\toolchains\llvm\prebuilt\windows-x86_64\bin\aarch64-linux-android28-clang.cmd']
cpp = ['C:\Users\<your_user_name>\AppData\Local\Android\Sdk\ndk\27.2.12479018\toolchains\llvm\prebuilt\windows-x86_64\bin\aarch64-linux-android28-clang++.cmd']
c_ld = ['C:\Users\<your_user_name>\AppData\Local\Android\Sdk\ndk\27.2.12479018\toolchains\llvm\prebuilt\windows-x86_64\bin\ld.lld']
cpp_ld = ['C:\Users\<your_user_name>\AppData\Local\Android\Sdk\ndk\27.2.12479018\toolchains\llvm\prebuilt\windows-x86_64\bin\ld.lld']
strip = ['C:\Users\<your_user_name>\AppData\Local\Android\Sdk\ndk\27.2.12479018\toolchains\llvm\prebuilt\windows-x86_64\bin\llvm-strip']

Configure and compile the MAF library and media pipeline plugins

  • libmaf and C# bindings are enabled by default.
  • the avpipeline plugin needs explicit configuration, the avcodec_dir must point to a subdirectory of the project where platfomrm specfic dependencies have been copied:
cd rt-xr-maf-native
meson setup --wipe -Davpipeline=true -Davpipeline:avcodec_dir=external/avcodec/android/arm64-v8a build/android/arm64-v8a --cross-file crossfile/android-arm64-v8a
meson compile -C build/android/arm64-v8a

Install the media pipeline factory and plugins into the Unity project

Assuming rt-xr-unity-player repository has been cloned in a sibling directory ../rt-xr-unity-player, run the following commands with the correct path that applies to your installation:

export ANDROID_NDK_HOME='/c/Users/<your_user_name>/AppData/Local/Android/Sdk/ndk/27.2.12479018'
cd rt-xr-maf-native
scripts/install_android.sh ../rt-xr-unity-player/Packages/rt.xr.maf

The script copies the following:

  • all compiled libraries from rt-xr-maf-native/build/android/arm64-v8a/ to rt-xr-unity-player/Packages/rt.xr.maf/bin/android/arm64/
  • C# bindings source code from rt-xr-maf-native/subprojects/maf_csharp/swig/ to rt-xr-unity-player/Packages/rt.xr.maf/maf/swig/
  • avpipeline dependencies from rt-xr-maf-native/subprojects/avpipeline/external/avcodec/android/arm64-v8a/lib/ to rt-xr-unity-player/Packages/rt.xr.maf/dependencies/ffmpeg/7.1/android/arm64 along with the related LICENSE
  • libc++ from $ANDROID_NDK_HOME/toolchains/llvm/prebuilt/$ANDROID_NDK_HOSTNAME/sysroot/usr/lib/aarch64-linux-android/libc++_shared.so to rt-xr-unity-player/Packages/rt.xr.maf/dependencies/libc++/android/arm64

Make sure all the *.so libraries are configured properly in the Unity Editor.

Configure shared libraries in Unity project

For each library, in the inspector panel:

  • Android platform must be checked
  • arm64 must be selected

The configuration is stored in Unity’s *.meta sidecar files and are tracked in the Unity repository. Unity removes the *.meta files if the resource they reference is not found when opening a project.

Step 3: Configure the glTF asset to be loaded by the XR Unity player

Clone the rt-xr-content repository. This requires git LFS to be installed on your system.

git clone https://github.com/5G-MAG/rt-xr-content.git

Push glTF content to the Meta Quest 3, for instance the “Studio Apartment”:

cd rt-xr-content
adb push ./studio_apartment /storage/emulated/0/Android/data/com.fivegmag.rtxrplayer/files/studio_apartment

Open the rt-xr-unity-player directory as an existing project from Unity Hub.

Now configure the glTF asset in the Unity project by adding the path, e.g. /storage/emulated/0/Android/data/com.fivegmag.rtxrplayer/files/studio_apartment/studio_apartment.gltf

Meta Quest scene configuration

Step 4: Build and run the Unity project

In the Unity Editor:

  1. Locate the File > Build Settings menu
  2. Make sure that Android is the selected platform, Switch Platform if needed
  3. Ensure that MetaQuestARF is the default scene.
  4. Select the device on which the application will be installed.
  5. Hit Build and Run to compile the project and install it on the mobile device

Meta Quest build settings

Step 5: Launch the player

Locate and launch the player in the Meta Quest 3.

Troubleshooting

Ensure the project is configured for OpenXR with Meta Quest support: Unity project XR configuration

Ensure the Meta Quest interaction profiles are configured: Meta Quest XR configuration