Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Godot Android plugins

前言

Android plugins are powerful tools to extend the capabilities of the Godot engine by tapping into the functionality provided by Android platforms and ecosystem.

For example in Godot 4, Android plugins are used to support multiple Android-based XR platforms without encumbering the core codebase with vendor specific code or binaries.

Android 插件

Version 1 (v1) of the Android plugin system was introduced in Godot 3 and compatible with Godot 4.0 and 4.1. That version allowed developers to augment the Godot engine with Java, Kotlin and native functionality.

Starting in Godot 4.2, Android plugins built on the v1 architecture are now deprecated. Instead, Godot 4.2 introduces a new Version 2 (v2) architecture for Android plugins.

v2 Architecture

备注

Godot Android plugin leverages the Gradle build system.

Building on the previous v1 architecture, Android plugins continue to be derived from the Android archive library.

At its core, a Godot Android plugin v2 is an Android library with a dependency on the Godot Android library, and a custom Android library manifest.

This architecture allows Android plugins to extend the functionality of the engine with:

  • Android platform APIs

  • Android libraries

  • Kotlin and Java libraries

  • Native libraries (via JNI)

  • GDExtension libraries

Each plugin has an init class extending from the GodotPlugin class which is provided by the Godot Android library.

The GodotPlugin class provides APIs to access the running Godot instance and hook into its lifecycle. It is loaded at runtime by the Godot engine.

v2 Packaging format

v1 Android plugins required a custom gdap configuration file that was used by the Godot Editor to detect and load them. However this approach had several drawbacks, primary ones being that it lacked flexibility and departed from the existing Godot EditorExportPlugin format, delivery and installation flow.

This has been resolved for v2 Android plugins by deprecating the gdap packaging and configuration mechanism in favor of the existing Godot EditorExportPlugin packaging format. The EditorExportPlugin API in turn has been extended to properly support Android plugins.

Building a v2 Android plugin

A github project template is provided at https://github.com/m4gr3d/Godot-Android-Plugin-Template as a quickstart for building Godot Android plugins for Godot 4.2+. You can follow the template README to set up your own Godot Android plugin project.

To provide further understanding, here is a break-down of the steps used to create the project template:

  1. Create an Android library module using these instructions

  2. Add the Godot Android library as a dependency by updating the module's gradle build file:

    dependencies {
    implementation("org.godotengine:godot:4.2.0.stable")
}

The Godot Android library is hosted on MavenCentral, and updated for each release.

  1. Create GodotAndroidPlugin, an init class for the plugin extending GodotPlugin.

    • If the plugin exposes Kotlin or Java methods to be called from GDScript, they must be annotated with @UsedByGodot. The name called from GDScript must match the method name exactly. There is no coercing snake_case to camelCase. For example, from GDScript:

      if Engine.has_singleton("MyPlugin"):
    var singleton = Engine.get_singleton("MyPlugin")
    print(singleton.myPluginFunction("World"))

    • If the plugin uses signals, the init class must return the set of signals used by overriding GodotPlugin::getPluginSignals(). To emit signals, the plugin can use the GodotPlugin::emitSignal(...) method.

  2. Update the plugin AndroidManifest.xml file with the following meta-data:

    <meta-data
    android:name="org.godotengine.plugin.v2.[PluginName]"
    android:value="[plugin.init.ClassFullName]" />

Where:

  • PluginName is the name of the plugin

  • plugin.init.ClassFullName is the full component name (package + class name) of the plugin init class (e.g: org.godotengine.plugin.android.template.GodotAndroidPlugin).

  1. Create the EditorExportPlugin configuration to package the plugin. The steps used to create the configuration can be seen in the Packaging a v2 Android plugin section.

Building a v2 Android plugin with GDExtension capabilities

Similar to GDNative support in v1 Android plugins, v2 Android plugins support the ability to integrate GDExtension capabilities.

A github project template is provided at https://github.com/m4gr3d/GDExtension-Android-Plugin-Template as a quickstart for building GDExtension Android plugins for Godot 4.2+. You can follow the template's README to set up your own Godot Android plugin project.

Migrating a v1 Android plugin to v2

Use the following steps if you have a v1 Android plugin you want to migrate to v2:

  1. Update the plugin's manifest file:

    • Change the org.godotengine.plugin.v1 prefix to org.godotengine.plugin.v2

  2. Update the Godot Android library build dependency:

    • You can continue using the godot-lib.<version>.<status>.aar binary from Godot's download page if that's your preference. Make sure it's updated to the latest stable version.

    • Or you can switch to the MavenCentral provided dependency:

      dependencies {
    implementation("org.godotengine:godot:4.2.0.stable")
}

  3. After updating the Godot Android library dependency, sync or build the plugin and resolve any compile errors:

    • The Godot instance provided by GodotPlugin::getGodot() no longer has access to a android.content.Context reference. Use GodotPlugin::getActivity() instead.

  4. Delete the gdap configuration file(s) and follow the instructions in the Packaging a v2 Android plugin section to set up the plugin configuration.

Packaging a v2 Android plugin

As mentioned, a v2 Android plugin is now provided to the Godot Editor as an EditorExportPlugin plugin, so it shares a lot of the same packaging steps.

  1. Add the plugin output binaries within the plugin directory (e.g: in addons/<plugin_name>/)

  2. Add the tool script for the export functionality within the plugin directory (e.g: in addons/<plugin_name>/)

    • The created script must be a @tool script, or else it will not work properly

    • The export tool script is used to configure the Android plugin and hook it within the Godot Editor's export process. It should look something like this:

      @tool
extends EditorPlugin

# A class member to hold the editor export plugin during its lifecycle.
var export_plugin : AndroidExportPlugin

func _enter_tree():
    # Initialization of the plugin goes here.
    export_plugin = AndroidExportPlugin.new()
    add_export_plugin(export_plugin)


func _exit_tree():
    # Clean-up of the plugin goes here.
    remove_export_plugin(export_plugin)
    export_plugin = null


class AndroidExportPlugin extends EditorExportPlugin:
    # Plugin's name.
    var _plugin_name = "<plugin_name>"

    # Specifies which platform is supported by the plugin.
    func _supports_platform(platform):
        if platform is EditorExportPlatformAndroid:
            return true
        return false

    # Return the paths of the plugin's AAR binaries relative to the 'addons' directory.
    func _get_android_libraries(platform, debug):
        if debug:
            return PackedStringArray(["<paths_to_debug_android_plugin_aar_binaries>"])
        else:
            return PackedStringArray(["<paths_to_release_android_plugin_aar_binaries>"])

    # Return the plugin's name.
    func _get_name():
        return _plugin_name

    • Here are the set of EditorExportPlugin APIs most relevant to use in this tool script:

      The _get_android_manifest_* methods allow the plugin to automatically provide changes to the app's manifest which are preserved when the Godot Editor is updated, resolving a long standing issue with v1 Android plugins.

  3. Create a plugin.cfg. This is an INI file with metadata about your plugin:

    [plugin]

name="<plugin_name>"
description="<plugin_description>"
author="<plugin_author>"
version="<plugin_version>"
script="<relative_path_to_the_export_tool_script>"

For reference, here is the folder structure for the Godot Android plugin project template. At build time, the contents of the export_scripts_template directory as well as the generated plugin binaries are copied to the addons/<plugin_name> directory:

export_scripts_template/
|
+--export_plugin.gd         # export plugi