部署到 Android

部署到 Android

场景布置

多数独立头显运行在 Android 上，并且 OpenXR 支持正在逐步推广到这些平台。

在遵循此处的 OpenXR 特定说明之前，你需要首先设置你的系统以导出到 Android 平台，包括：

安装 OpenJDK 17
安装 Android Studio
创建 debug.keystore
在 Godot 中配置 Android SDK 和 debug.keystore 的位置

详情请参见为 Android 导出，完成所需配置后再返回此处。

Gradle Android 构建

备注

最初，官方对 Android 平台的支持并未添加到 OpenXR 规范中，这导致各大供应商都创建了自定义加载器以在其头戴设备上实现 OpenXR。尽管从长远角度来看，所有供应商都终将转移到官方的 OpenXR 加载器；但就当下来说，这些加载器需要添加到你的项目中。

为了将特定供应商的 OpenXR 加载器包含到你的项目中，你需要先设置一个 Gradle Android 构建。

在项目菜单中选择安装 Android 构建模板…：

这将在你的项目中创建一个名为 android 的文件夹，包含在 Android 上运行所需的所有运行时文件。现在你可以自定义这个安装，Godot 不会在编辑器中显示这个文件夹，但你可以通过文件浏览器找到它。

你可以在这里阅读更多关于 Gradle 构建的信息：Android 的 Gradle 构建。

Installing the vendors plugin

警告

在 Godot 4.2 中，Android 插件的结构进行了重构，加载器插件被重命名为供应商插件——因为它现在不仅仅包括加载器了。如果你安装旧版本加载器插件，需要将其从 android/plugins 文件夹中删除。

The vendors plugin can be downloaded from the asset library, search for “OpenXR vendors” and install the plugin:

You will find the installed files inside the addons folder.

Alternatively you can manually install the vendors plugin by downloading the v2.x version of the plugin from the release page here.

你需要将压缩文件中的 assets/addons/godotopenxrvendors 文件夹复制到你的项目的 addons 文件夹中。

你可以在这里找到 vendors 插件的主仓库。

Enabling the vendors plugin

在导出设置可访问之前，需要启用供应商插件。打开 Project 并选择 Project Settings… 。转到 Plugins 选项卡。启用 GodotOpenXRVendors 插件。

备注

This is no longer required from vendors plugin 2.0.3 onwards as it now uses GDExtension. The plugin will not be shown in this list. You can verify it is installed correctly by checking if the export presets contain the entries described below.

创建导出预设

不同的设备有不同的加载器，因此你需要为每个设备分别准备导出预设。

打开 Project 并选择 Export… 。点击 Add… 并选择 Android 。接下来，将导出预设的名称更改为你正在设置的设备的名称，比如 Meta Quest 。启用 Use Gradle Build 。如果你想使用一键部署（如下所述），记得启用 Runnable 。

If the vendors plugins were installed correctly you should find entries for the different headsets, select the entry for meta:

同时将 XR Mode 改为 OpenXR 。

滚动到列表底部，你会发现额外的 XR 功能部分，目前只有 Meta XR Features 可用。此处的手部追踪和透视设置目前仅适用于 Meta Quest，如果你希望使用这些功能，需要选择适当的设置。

现在，你可以为其他设备重复相同的过程。

备注

Meta Quest、Pico 和 Lynx R1 头戴设备各有独立的加载器。

除了以上三个，第四个选项是官方 Khronos 加载器 —— 目前，这个加载器已经在 Magic Leap 2 和独立的 HTC 头戴设备上进行了测试，在可预见的未来里，会有越来越多的头显设备会适配该加载器。

警告

虽然 Vulkan 渲染器针对移动设备进行了优化，但目前我们仍在解决适配问题。就现在而言，强烈建议开发者在针对基于 Android 的 XR 设备时使用兼容性渲染器（OpenGL）。

通过 Godot 编辑器在设备上运行

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 一键部署:

正确识别某些平台上的某些设备，可能需要执行额外步骤，请务必查阅你头戴设备供应商的开发者文档。

例如，对于 Meta Quest 2，你需要在头戴设备上启用开发者模式，并且如果你在 Windows 上开发，还需安装特定 ADB 驱动程序。更多详细信息，请参阅`官方 Meta Quest 开发者文档 <https://developer.oculus.com/documentation/native/android/mobile-device-setup/>`_。

如果你在一键部署方面遇到了问题，可参考 Troubleshooting section。