Godot Android 库

适用于 Android 平台的 Godot 引擎旨在作为 Android 库 使用。该架构可在 Android 平台上实现多项关键功能：

  • 能够将 Gradle 构建系统整合进 Godot 编辑器，从而提供了利用 Android 生态系统中更多组件的能力，比如库和工具

  • 能够使引擎具有便携性和可嵌入性:

    • 在使 Godot 编辑器能够移植到 Android 和移动 XR 设备中发挥关键作用

    • 在现有代码库中集成和重复使用 Godot 功能发挥关键作用

下面我们描述了该架构支持的一些用例和场景。

使用 Godot Android 库

Godot Android 库以 AAR 归档文件的形式打包，连同其 文档 寄存在 MavenCentral 上。

它提供了在 Android 平台上访问 Godot 应用程序接口和功能的途径，适用于以下不完全用例。

Godot Android 插件

Android 插件是一种强大的工具，可利用 Android 平台和生态系统提供的功能来扩展 Godot 引擎的功能。

Android 插件是一个依赖于 Godot Android 库的 Android 库，插件使用该库集成到引擎的生命周期中，并访问 Godot API，从而赋予其强大的功能，例如 GDExtension 支持，允许根据需要更新/修改引擎行为。

详情见 Godot Android 插件。

将 Godot 嵌入到已有 Android 项目中

Godot 引擎可以嵌入现有的 Android 应用程序或库中，使开发人员能够利用成熟且经过考验的代码和库，更适合特定任务。

托管组件负责通过 Godot 的 Android API 来驱动引擎的生命周期。这些 API 还可用于在主机和嵌入式 Godot 实例之间提供双向通信，从而更好地控制所需的体验。

We showcase how this is done using a sample Android app that embeds the Godot Engine as an Android view, and uses it to render 3D glTF models.

The GLTF Viewer sample app uses an Android RecyclerView component to create a list of glTF items, populated from Kenney's Food Kit pack. When an item on the list is selected, the app's logic interacts with the embedded Godot Engine to render the selected glTF item as a 3D model.

../../../_images/gltf_viewer_sample_app_screenshot.webp

示例应用程序源代码可以在 GitHub 上找到。按照其 README 上的说明来进行构建和安装。

下面我们详细介绍了创建 GLTF 查看器应用程序的步骤。

警告

目前，每个进程仅支持单个 Godot 引擎实例。你可以使用 android:process 属性 来配置 Android Activity 运行的进程。

警告

不支持自动调整大小/方向配置事件，这些事件可能会导致系统崩溃。你可以禁用这些事件：

1. 创建 Android 应用

备注

Android 示例应用是使用 Android Studio 和 Gradle 构建系统创建的。

Android 生态系统提供了多种工具、集成开发环境（IDE）和构建系统来创建 Android 应用程序，因此你可以自由选择自己熟悉的方式，并相应地更新下面的步骤（欢迎为这份文档做出贡献！）。

  • 设置一个 Android 应用程序项目，可以是全新的空项目，也可以是现有的项目

  • 添加指向 Godot Android 库的 Maven 依赖项

    • 如果使用 gradle，请在应用的 gradle 构建文件的 dependency 部分添加以下内容。确保将 <version> 更新为 Godot Android 库的最新版本：

    implementation("org.godotengine:godot:<version>")

  • 如果使用 gradle，请在应用的 gradle 构建文件的 android > defaultConfig 部分包含以下 aaptOptions 配置。这样就可以让 gradle 在构建应用二进制文件时包含 Godot 的隐藏目录。

android {

  defaultConfig {
      // The default ignore pattern for the 'assets' directory includes hidden files and
      // directories which are used by Godot projects, so we override it with the following.
      aaptOptions {
          ignoreAssetsPattern "!.svn:!.git:!.gitignore:!.ds_store:!*.scc:<dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"
      }
    ...

  • 创建或更新应用程序的 Activity，用于承载 Godot 引擎实例。即示例应用中的 MainActivity

    • 用于承载的 Activity 应当实现 GodotHost 接口

    • 示例应用程序使用 片段 来组织其UI，所以它使用 GodotFragment <https://github.com/godotengine/godot/blob/master/platform/android/java/lib/src/org/godotengine/godot/GodotFragment.java> ，一个由 Godot Android 库提供的片段组件，用于自动托管和管理 Godot 引擎实例。

    private var godotFragment: GodotFragment? = null

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    setContentView(R.layout.activity_main)

    val currentGodotFragment = supportFragmentManager.findFragmentById(R.id.godot_fragment_container)
    if (currentGodotFragment is GodotFragment) {
        godotFragment = currentGodotFragment
    } else {
        godotFragment = GodotFragment()
        supportFragmentManager.beginTransaction()
            .replace(R.id.godot_fragment_container, godotFragment!!)
            .commitNowAllowingStateLoss()
    }

    ...

备注

Godot Android 库还提供 GodotActivity，这是一个可以被扩展以自动托管和管理 Godot 引擎实例的 Activity 组件。

或者，应用程序可以直接创建一个 Godot 实例，来托管和管理。

<activity android:name=".MainActivity"
    android:screenOrientation="fullUser"
    android:configChanges="orientation|screenSize|smallestScreenSize|screenLayout"
    android:exported="true">

    ...
</activity>

2. 创建 Godot 项目

备注

在 Android 上，Godot 的项目文件会被导入到所生成 apk 二进制文件的 assets 目录中。

通过在 Android 应用程序的 assets 目录中创建 Godot 项目，我们利用该架构将 Android 应用程序和 Godot 项目绑定在一起。

请注意，也可以在单独的目录中创建 Godot 项目，并将其导出为`PCK 或 ZIP 文件 <https://docs.godotengine.org/en/stable/tutorials/export/exporting_projects.html#pck-versus-zip-pack-file-formats>`_ 到 Android 应用程序的 assets 目录。使用这种方法需要使用 GodotHost#getCommandLine() 将 --main-pack <pck_or_zip_filepath_relative_too_assets_dir> 参数传递给托管的 Godot 引擎实例。

下面的说明和示例应用程序采用了第一种方法，即在 Android 应用程序的 assets 目录中创建 Godot 项目。

  • 如上文 note 所述，打开 Godot 编辑器，直接在 Android 应用程序项目的 assets 目录下创建一个 Godot 项目（无子文件夹）

    • 请参阅示例应用程序的 Godot 项目 以获取参考

  • 按需配置 Godot 项目

  • 按需更新 Godot 项目的脚本逻辑

    • 示例项目中的脚本逻辑会查询运行时的 GodotPlugin 实例，并将其注册到应用逻辑所发出的信号

    • The app logic fires a signal every time an item is selected in the list. The signal contains the filepath of the glTF model, which is used by the gdscript logic to render the model.

    extends Node3D

# Reference to the gltf model that's currently being shown.
var current_gltf_node: Node3D = null

func _ready():
  # Default asset to load when the app starts
  _load_gltf("res://gltfs/food_kit/turkey.glb")

  var appPlugin = Engine.get_singleton("AppPlugin")
  if appPlugin:
    print("App plugin is available")

    # Signal fired from the app logic to update the gltf model being shown
    appPlugin.connect("show_gltf", _load_gltf)
  else:
    print("App plugin is not available")


# Load the gltf model specified by the given path
func _load_gltf(gltf_path: String):
  if current_gltf_node != null:
    remove_child(current_gltf_node)

  current_gltf_node = load(gltf_path).instantiate()

  add_child(current_gltf_node)

3. 构建并运行应用

完成对 Godot 项目的配置后，请构建并运行该 Android 应用。如果设置无误，宿主 Activity 就会在启动时初始化内嵌的 Godot 引擎。Godot 引擎会在 assets 目录中查找要加载的项目文件（除非配置中要求查找 main pack），然后开始运行项目。

应用在设备上运行时，你可以通过 Android logcat 来调查报错和崩溃的情况。

作为参考，你可以查看一下 GLTF 查看器示例应用的构建和安装步骤。