Merge pull request #7567 from dsnopek/improved-meta-quest-setup

Make the steps for deploying to Meta Quest 2 (and other Android headsets) clearer

tutorials/export/one-click_deploy.rst

@@ -59,6 +59,8 @@ Using one-click deploy
 
 .. image:: img/remote_debug.webp
 
+.. _doc_one-click_deploy_troubleshooting:
+
 Troubleshooting
 ---------------
 

tutorials/xr/deploying_to_android.rst

@@ -5,16 +5,25 @@ Deploying to Android
 
 Setup
 ------------
-Most mobile headsets run on Android and OpenXR support is making its way to these platforms. There are specific requirements for deploying XR projects to Android.
-For general requirements around exporting to Android, please first read :ref:`doc_exporting_for_android`.
+Most mobile headsets run on Android and OpenXR support is making its way to these platforms.
+
+Before following the OpenXR-specific instructions here, you'll need to first setup your system to export to Android in general, including:
+
+- Installing OpenJDK 11
+- Installing Android Studio
+- Creating a debug.keystore
+- Configuring the location of the Android SDK and debug.keystore in Godot
+
+See :ref:`doc_exporting_for_android` for the full details, and return here when you've finished these steps.
+
+Custom Android build
+--------------------
 
 .. note::
     Official support for the Android platform wasn't added to the OpenXR specification initially resulting in various vendors creating custom loaders to make OpenXR available on their headsets.
     While the long term expectation is that all vendors will adopt the official OpenXR loader, for now these loaders need to be added to your project.
 
-Custom Android build
---------------------
-In order to deploy the loaders into your project you will need to setup a custom Android build.
+In order to include the vendor-specific OpenXR loader into your project, you will need to setup a custom Android build.
 
 Select **Install Android Build Template...** from the **Project** menu:
 
@@ -35,14 +44,15 @@ There is a subfolder called **plugins** containing the new files.
 
 You can find the main repository of the loader plugin `here <https://github.com/GodotVR/godot_openxr_loaders>`__.
 
-Creating the export templates
------------------------------
-You will need to setup a separate export template for each device as each device will need its own loader included.
+Creating the export presets
+---------------------------
+You will need to setup a separate export preset for each device, as each device will need its own loader included.
 
 Open **Project** and select **Export..**.
 Click on **Add..** and select **Android**.
-Next change the name of the export profile for the device you're setting this up for, say **Meta Quest**.
+Next change the name of the export preset for the device you're setting this up for, say **Meta Quest**.
 And enable **Use Gradle Build**.
+If you want to use one-click deploy (described below), ensure that **Runnable** is enabled.
 
 If the loader plugins were installed correctly you should find entries for the different headsets, select the entry for meta:
 
@@ -56,7 +66,7 @@ The hand tracking and passthrough settings here currently only work for the Meta
 .. image:: img/xr_export_features.webp
 
 
-Now you can repeat the same process for the other devices. Note that if you wish to test your game with Godots one-click deploy, you have to mark the export profile for your device as **Runnable** so Godot knows which loader to deploy.
+Now you can repeat the same process for the other devices.
 
 .. note::
     There are separate loaders for the Meta Quest, Pico and Lynx R1 headsets.
@@ -70,3 +80,14 @@ Now you can repeat the same process for the other devices. Note that if you wish
 
     Note that we are awaiting driver updates on various devices before Vulkan support will work on these.
 
+Running on your device from the Godot editor
+--------------------------------------------
+If you've setup your export settings as described above, and your headset is connected to your computer and correctly recognized, you can launch it directly from the Godot editor using :ref:`doc_one-click_deploy`:
+
+.. image:: img/android_one_click_deploy.webp
+
+For some devices on some platforms, you may need to perform some extra steps in order for your device to be recognized correctly, so be sure to check the developer documentation from your headset vendor.
+
+For example, with the Meta Quest 2, you need to enable developer mode on the headset, and if you're on Windows, you'll need to install special ADB drivers. See the `official Meta Quest developer documentation <https://developer.oculus.com/documentation/native/android/mobile-device-setup/>`_ for more details.
+
+If you're having any issues with one-click deploy, check the :ref:`Troubleshooting section <doc_one-click_deploy_troubleshooting>`.