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 实例之间提供双向通信，从而更好地控制所需的体验。

我们展示了如何使用示例 Android 应用程序来完成此操作，该应用程序将 Godot 引擎嵌入为 Android 视图，并使用它来渲染 3D GLTF 模型。

GLTF Viewer 示例应用程序使用 Android RecyclerView 组件 来创建 GLTF 项目列表，该列表由 `Kenney’s Food Kit pack<https://kenney.nl/assets/food-kit>`_ 填充 。当选择列表中的项目时，应用程序的逻辑与嵌入式 Godot 引擎交互，将选定的 GLTF 项目渲染为 3D 模型。

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

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

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

警告

目前，每个进程仅支持单个 Godot 引擎实例。你可以使用 `android:process 属性<https://developer.android.com/guide/topics/manifest/activity-element#proc>`_ 来配置 Android Activity 运行的进程。

警告

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

1. 创建 Android 应用

备注

The Android sample app was created using Android Studio and using Gradle as the build system.

The Android ecosystem provides multiple tools, IDEs, build systems for creating Android apps so feel free to use what you’re familiar with, and update the steps below accordingly (contributions to this documentation are welcomed as well!).

  • Set up an Android application project. It may be a brand new empty project, or an existing project

  • Add the maven dependency for the Godot Android library

    • If using gradle, add the following to the dependency section of the app’s gradle build file. Make sure to update <version> to the latest version of the Godot Android library:
    1. implementation("org.godotengine:godot:<version>")

  • If using gradle, include the following aaptOptions configuration under the android > defaultConfig section of the app’s gradle build file. Doing so allows gradle to include Godot’s hidden directories when building the app binary.

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

  • Create / update the application’s Activity that will be hosting the Godot Engine instance. For the sample app, this is MainActivity

    • The host Activity should implement the GodotHost interface

    • The sample app uses Fragments to organize its UI, so it uses GodotFragment, a fragment component provided by the Godot Android library to automatically host and manage the Godot Engine instance.

    1. private var godotFragment: GodotFragment? = null
    3. override fun onCreate(savedInstanceState: Bundle?) {
    4.     super.onCreate(savedInstanceState)
    6.     setContentView(R.layout.activity_main)
    8.     val currentGodotFragment = supportFragmentManager.findFragmentById(R.id.godot_fragment_container)
    9.     if (currentGodotFragment is GodotFragment) {
    10.         godotFragment = currentGodotFragment
    11.     } else {
    12.         godotFragment = GodotFragment()
    13.         supportFragmentManager.beginTransaction()
    14.             .replace(R.id.godot_fragment_container, godotFragment!!)
    15.             .commitNowAllowingStateLoss()
    16.     }
    18.     ...

备注

The Godot Android library also provide GodotActivity, an Activity component that can be extended to automatically host and manage the Godot Engine instance.

Alternatively, applications can directly create a Godot instance, host and manage it themselves.

  1. <activity android:name=".MainActivity"
  2.     android:screenOrientation="fullUser"
  3.     android:configChanges="orientation|screenSize|smallestScreenSize|screenLayout"
  4.     android:exported="true">
  6.     ...
  7. </activity>

2. Create the Godot project

备注

On Android, Godot’s project files are exported to the assets directory of the generated apk binary.

We leverage that architecture to bind our Android app and Godot project together by creating the Godot project in the Android app’s assets directory.

Note that it’s also possible to create the Godot project in a separate directory and export it as a PCK or ZIP file to the Android app’s assets directory. Using this approach requires passing the --main-pack <pck_or_zip_filepath_relative_to_assets_dir> argument to the hosted Godot Engine instance using GodotHost#getCommandLine().

The instructions below and the sample app follow the first approach of creating the Godot project in the Android app’s assets directory.

  • As mentioned in the note above, open the Godot Editor and create a Godot project directly (no subfolder) in the assets directory of the Android application project

  • Configure the Godot project as desired

  • Update the Godot project script logic as needed

    • For the sample app, the script logic queries for the runtime GodotPlugin instance and uses it to register for signals fired by the app logic

    • 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:

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

    else:

    1. print("App plugin is not available")
  1. # Load the gltf model specified by the given path
  2. func _load_gltf(gltf_path: String):
  3.   if current_gltf_node != null:
  4.     remove_child(current_gltf_node)
  6.   current_gltf_node = load(gltf_path).instantiate()
  8.   add_child(current_gltf_node)
  9. ```

3. Build and run the app

Once you complete configuration of your Godot project, build and run the Android app. If set up correctly, the host Activity will initialize the embedded Godot Engine on startup. The Godot Engine will check the assets directory for project files to load (unless configured to look for a main pack), and will proceed to run the project.

While the app is running on device, you can check Android logcat to investigate any errors or crashes.

For reference, check the build and install instructions for the GLTF Viewer sample app.