Godot Android plugin re-architecture

[m4gr3d]

Third scheduled Android refactor (after #76821 and #78958) for the upcoming Godot 4.2 release.

TLDR;

This refactor focuses on cleaning up and restoring full functionality for Godot Android plugins, which have effectively been (partially) broken since the Godot 4.0 release.

Godot 4.x Android plugins (v2)

Versioning

In Godot 3.x, the following metadata was required in the plugin's AndroidManifest to declare it:

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

For Godot 4.2 and higher, the metadata remains mostly the same, but the version is bumped to v2:

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

At runtime, the engine only loads plugins with the org.godotengine.plugin.v2 prefix. The GodotPlugin base class has been modified in a non-backward compatible manner, so Godot 3.x Android plugins (with the org.godotengine.plugin.v1 prefix) are no longer supported in Godot 4.2 and higher.

Packaging

The plugin's packaging was re-done in #78958, deprecating the use of the .gdap format used in Godot 3.x in order to better align with Godot other plugin types. The documentation will be updated in a follow-up PR to describe the new packaging format.

GDExtension integration

In Godot 3.x, Godot Android plugins provided the ability to integrate GDNative functionality.
Similarly, this PR adds the ability for v2 Godot Android plugins to integrate with GDExtension functionality starting with Godot 4.2.

In addition, this PR fixes the issue that prevented the Godot Android editor from loading and using GDExtension plugins

Samples

• Godot Android samples project: https://github.com/m4gr3d/Godot-Android-Samples/blob/master/plugins/README.md
  • PR adding the GDExtension sample: Add an Android GDExtension plugin sample m4gr3d/Godot-Android-Samples#2
• Android plugin template project: https://github.com/m4gr3d/Godot-Android-Plugin-Template
• GDExtension Android plugin template project: https://github.com/m4gr3d/GDExtension-Android-Plugin-Template

Remaining TODOs

• Create github template projects to facilitate the creation of a v2 Godot Android plugin
• Update the Godot Android plugin documentation
• Blog post to announce the change early to give Android plugins writer the opportunity to migrate early

[tokengamedev]

Will wait on the documentation to be completed, to test both the documentation and plugin architecture itself
Will migrate godot-android modules to 4.2 after that

[dsnopek]

Thanks!

Looking through the PR and the sample, it looks like including a GDExtension as part of an Android plugin works like this:

1. The .gdextension file has:

[exportable]
android=false

... so that the .so file doesn't get include in the export like it normally would with a GDExtension.

2. The Android plugin adds an EditorExportPlugin which tells Godot to include the .aar file (which I think contains the .so via the Gradle build?) into the export

3. The GodotPlugin (in Java/Kotlin) implements the getPluginGDExtensionModulesPaths() method which will return a list containing the path to the .gdextension file, which will eventually get loaded via OS_Android::load_platform_gdextensions()

Do I have this right?

If so, this seems a little convoluted. Is there a reason we couldn't skip step nr 2, by having an [android] section or something in the .gdextension file, to tell the GDExtensionExportPlugin to include the .aar files in the export rather than the .so's, so each plugin doesn't need to implement an EditorExportPlugin? Something like:

[android]
debug=bin/MyExtension.debug.aar
release=bin/MyExtension.release.aar

I'm also a little unclear on why OS_Android::load_platform_gdextensions() needs to load the GDExtensions rather than the normal loading mechanism? It seems run right after the normal mechanism, and actually I'm not sure why the normal mechanism doesn't pick up the .gdextension files. Are the .gdextension files embedded in the .aar file too?

Sorry for all the dumb questions - I think I'm missing a bunch of context around how Android plugins work :-)

[m4gr3d]

Thanks!

Looking through the PR and the sample, it looks like including a GDExtension as part of an Android plugin works like this:

1. The .gdextension file has:

[exportable]
android=false

... so that the .so file doesn't get include in the export like it normally would with a GDExtension.

2. The Android plugin adds an EditorExportPlugin which tells Godot to include the .aar file (which I think contains the .so via the Gradle build?) into the export

That's correct, the plugin's aar binary contains the .so file so we need to let GDExtensionExportPlugin know not to export the .so file a second time.

3. The GodotPlugin (in Java/Kotlin) implements the getPluginGDExtensionModulesPaths() method which will return a list containing the path to the .gdextension file, which will eventually get loaded via OS_Android::load_platform_gdextensions()

Do I have this right?

If so, this seems a little convoluted. Is there a reason we couldn't skip step nr 2, by having an [android] section or something in the .gdextension file, to tell the GDExtensionExportPlugin to include the .aar files in the export rather than the .so's, so each plugin doesn't need to implement an EditorExportPlugin? Something like:

[android]
debug=bin/MyExtension.debug.aar
release=bin/MyExtension.release.aar

Following #78958, all Android plugins are now EditorExportPlugin plugins as it allows to standardize around a common plugin format, and the capabilities provided by the (expanded) EditorExportPlugin api resolves numerous issues the previous 3.x Android format had.

From that perspective, this PR adds a new capability (gdextension) to 4.x Android plugins, so the approach then is to base off the EditorExportPlugin configuration, and update the gdextension config to match where needed.

I'm also a little unclear on why OS_Android::load_platform_gdextensions() needs to load the GDExtensions rather than the normal loading mechanism? It seems run right after the normal mechanism, and actually I'm not sure why the normal mechanism doesn't pick up the .gdextension files. Are the .gdextension files embedded in the .aar file too?

The proposed architecture covers two primary use-cases:

• Using Godot Android plugins within the Godot Editor
• Using Godot Android plugins within an Android app / game: on Android, both the Godot engine and the Godot Android plugins can be made available as AAR libraries that Android apps and games can integrate in their codebase.

When using a Godot Android plugin and exporting from the Godot Editor, the normal mechanism does pick up and load the GDExtensions and OS_Android::load_platform_gdextensions() becomes a no-op.

However the normal mechanism is set up by the Godot Editor export logic and it's not available when using different tools / IDEs.
So in the scenario where the Godot app / game is not built from the Godot Editor, the Godot engine relies on GodotPlugin::getPluginGDExtensionModulesPaths() and OS_Android::load_platform_gdextensions() to find the path to the gdextension config file at runtime and load it for use.

Are the .gdextension files embedded in the .aar file too?

Yes, when the AAR binary for a Godot Android plugin is generated, it contains the .gdextension config file to cover the use-case described above.

Sorry for all the dumb questions - I think I'm missing a bunch of context around how Android plugins work :-)

No dumb at all and please keep them coming! They help me figure out what I need to cover in the (in-progress) documentation!

[dsnopek]

Ok, thanks for the detailed explanation! This is definitely making a little more sense to me. :-)

The proposed architecture covers two primary use-cases:

• Using Godot Android plugins within the Godot Editor
• Using Godot Android plugins within an Android app / game: on Android, both the Godot engine and the Godot Android plugins can be made available as AAR libraries that Android apps and games can integrate in their codebase.

In the case of Android plugins that don't need to do anything special in the editor, would they still need to provide an EditorExportPlugin just to make sure the .aar files are included in export? For example, I'm imagining an ARCore plugin - it would provide some Java/Kotlin code and a GDExtension, but only needs to run in game. It'd be nice to avoid extra boilerplate, if possible.

Or, if the EditorExportPlugin is always required, could we use that to prevent exporting the .so file rather than adding the [exportable] section to the .gdextension file? I'm not sure I can think of another case where a GDExtension does have a library for the given platform, but we don't want to export it for that platform.

I think part of what feels weird here is that we're doing half of the export customization work in a custom EditorExportPlugin and the other half in the .gdextension file (via the GDExtensionExportPlugin). Is it possible to consolidate this in one place or the other? It'd be nice for the inclusion of the .aar files and exclusion of the .so files to be handled in the same place somehow.

In any case, I think I need to spend a little more time poking at the samples to improve my understanding of all this.

[m4gr3d]

In the case of Android plugins that don't need to do anything special in the editor, would they still need to provide an EditorExportPlugin just to make sure the .aar files are included in export? For example, I'm imagining an ARCore plugin - it would provide some Java/Kotlin code and a GDExtension, but only needs to run in game. It'd be nice to avoid extra boilerplate, if possible.

ARCore plugin is actually a good example for the functionality added by the EditorExportPlugin. When using an ARCore (or OpenXR) plugin, there's a need to modify the generated manifest to include metadata required by the plugin. The EditorExportPlugin provides apis so the plugin can insert the needed metadata at export time.

Here's an example from the OpenXR plugin: https://github.com/GodotVR/godot_openxr_loaders/blob/master/demo/addons/godotopenxr/export/meta/godot_openxr_meta_editor_export_plugin.gd#L88-L147

When nothing special is required besides providing access to the AAR binary, then export logic is fairly simple: https://github.com/m4gr3d/Godot-Android-Samples/blob/master/plugins/hello_world/src/main/assets/addons/hello_world_plugin/.export/hello_world_editor_export_plugin.gd

Or, if the EditorExportPlugin is always required, could we use that to prevent exporting the .so file rather than adding the [exportable] section to the .gdextension file? I'm not sure I can think of another case where a GDExtension does have a library for the given platform, but we don't want to export it for that platform.

I think part of what feels weird here is that we're doing half of the export customization work in a custom EditorExportPlugin and the other half in the .gdextension file (via the GDExtensionExportPlugin). Is it possible to consolidate this in one place or the other? It'd be nice for the inclusion of the .aar files and exclusion of the .so files to be handled in the same place somehow.

That was the first approach I looked into; the issue is that the GDExtensionExportPlugin is the one responsible for including the gdextension .so files during export, and there's no mechanism for another plugin to change its behavior (IMO, that's a good thing because you wouldn't want plugins to interfere with each other causing hard to trace issues).

As such the only mean I found to change its behavior is via the .gdextension config files.
The other alternative I considered was to have two .gdextension config files, one for the editor (if the plugin has editor functionality) that declares no support for Android, and one in the plugin AAR binary which declares support for Android and is loaded at runtime.. The issue with that approach is that you're increasing the burden on the developer by requiring them to track and keep in sync multiple config files..

[dsnopek]

As such the only mean I found to change its behavior is via the .gdextension config files.

What if we change it in a more Android-specific way? Like I mentioned above, I'm not sure I can think of any other use case for the [exportable] section in the .gdextension.

What if we added a different section like in my first comment, ex:

[android-plugin]
debug=bin/MyExtension.debug.aar
release=bin/MyExtension.release.aar

And then modify GDExtensionExportPlugin so that if we're exporting for Android, and it finds a matching entry in this section, it'll include the .aar file and exclude the .so file?

That has the advantage of (1) putting both these complementary export customizations in the same place, and (2) not having the super generic [exportable] section that's really actually just for this single Android plugin use case.

[m4gr3d]

As a follow-up from the GDExtension discussion, I've updated the configuration for Android plugins' gdextension:

• Removed the exportable section as it was deemed confusing
• Added a android_aar_plugin = [ true | false ] key to the configuration section

The presence of that field (with a true value) signals to the GDExtensionExportPlugin that the .so files for Android should not be exported as they are provided by the plugin AAR binary file.

[dsnopek]

• Added a android_aar_plugin = [ true | false ] key to the configuration section

I like the inclusion of "aar" in the name of the setting, that'll make it even more clear what this is for (as opposed to just android_plugin).

With regard to the GDExtension changes, I'm personally happy with this now!

I'm not really qualified to review the Android changes, but insofar as I've come to understand the Android plugin stuff while reviewing this, it generally makes sense to me how someone would include a GDExtension in their Android plugin.

[paddy-exe]

Alright I tried the PR on top of my ARCore PR changes. There are several errors that I get but it could be that I just haven't implemented the binding side in the extension correctly:

Error Message

* What went wrong:
Execution failed for task ':ARCore:externalNativeBuildDebug'.
> Build command failed.
  Error while executing process C:\Users\Patrick\AppData\Local\Android\Sdk\cmake\3.10.2.4988404\bin\ninja.exe with arguments {-C C:\Users\Patrick\Documents\Coding\XR\godot_arcore\plugin\.cxx\cmake\debug\arm64-v8a godot_arcore}
  ninja: Entering directory `C:\Users\Patrick\Documents\Coding\XR\godot_arcore\plugin\.cxx\cmake\debug\arm64-v8a'
  [1/2] Building CXX object CMakeFiles/godot_arcore.dir/src/main/cpp/register_types.cpp.o
  [2/2] Linking CXX shared library ..\..\..\..\build\intermediates\cmake\debug\obj\arm64-v8a\libgodot_arcore.so
  FAILED: ../../../../build/intermediates/cmake/debug/obj/arm64-v8a/libgodot_arcore.so
  cmd.exe /C "cd . && C:\Users\Patrick\AppData\Local\Android\Sdk\ndk\23.2.8568313\toolchains\llvm\prebuilt\windows-x86_64\bin\clang++.exe --target=aarch64-none-linux-android24 --gcc-toolchain=C:/Users/Patrick/AppData/Local/Android/Sdk/ndk/23.2.8568313/toolchains/llvm/prebuilt/windows-x86_64 --sysroot=C:/Users/Patrick/AppData/Local/Android/Sdk/ndk/23.2.8568313/toolchains/llvm/prebuilt/windows-x86_64/sysroot -fPIC -g -DANDROID -fdata-sections -ffunction-sections -funwind-tables -fstack-protector-strong -no-canonical-prefixes -D_FORTIFY_SOURCE=2 -Wformat -Werror=format-security  -std=c++17 -Wall -fno-limit-debug-info  -Wl,--build-id=sha1 -Wl,--no-rosegment -Wl,--fatal-warnings -Wl,--no-undefined -Qunused-arguments   -Wl -shared -Wl,-soname,libgodot_arcore.so -o ..\..\..\..\build\intermediates\cmake\debug\obj\arm64-v8a\libgodot_arcore.so CMakeFiles/godot_arcore.dir/src/main/cpp/arcore_interface.cpp.o CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_jni.cpp.o CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_plugin_wrapper.cpp.o CMakeFiles/godot_arcore.dir/src/main/cpp/register_types.cpp.o  -landroid -llog -lGLESv2 ../../../../build/arcore-native/jni/arm64-v8a/libarcore_sdk_c.so libgodot-cpp.a -latomic -lm && cd ."
  ld: error: undefined symbol: ARCorePluginWrapper::_get_surface
  >>> referenced by arcore_plugin_wrapper.cpp:0 (../../../../src/main/cpp/jni\arcore_plugin_wrapper.cpp:0)
  >>>               CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_plugin_wrapper.cpp.o:(ARCorePluginWrapper::ARCorePluginWrapper())
  >>> referenced by arcore_plugin_wrapper.cpp:0 (../../../../src/main/cpp/jni\arcore_plugin_wrapper.cpp:0)
  >>>               CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_plugin_wrapper.cpp.o:(ARCorePluginWrapper::ARCorePluginWrapper())
  >>> referenced by arcore_plugin_wrapper.cpp:0 (../../../../src/main/cpp/jni\arcore_plugin_wrapper.cpp:0)
  >>>               CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_plugin_wrapper.cpp.o:(ARCorePluginWrapper::initialize_wrapper(_JNIEnv*, _jobject*, _jobject*, _jobject*))
  >>> referenced 5 more times

  ld: error: undefined symbol: ARCorePluginWrapper::_is_activity_resumed
  >>> referenced by arcore_plugin_wrapper.cpp:0 (../../../../src/main/cpp/jni\arcore_plugin_wrapper.cpp:0)
  >>>               CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_plugin_wrapper.cpp.o:(ARCorePluginWrapper::ARCorePluginWrapper())
  >>> referenced by arcore_plugin_wrapper.cpp:0 (../../../../src/main/cpp/jni\arcore_plugin_wrapper.cpp:0)
  >>>               CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_plugin_wrapper.cpp.o:(ARCorePluginWrapper::ARCorePluginWrapper())
  >>> referenced by arcore_plugin_wrapper.cpp:0 (../../../../src/main/cpp/jni\arcore_plugin_wrapper.cpp:0)
  >>>               CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_plugin_wrapper.cpp.o:(ARCorePluginWrapper::initialize_wrapper(_JNIEnv*, _jobject*, _jobject*, _jobject*))
  >>> referenced 5 more times

  ld: error: undefined symbol: ARCorePluginWrapper::_get_display_rotation
  >>> referenced by arcore_plugin_wrapper.cpp:0 (../../../../src/main/cpp/jni\arcore_plugin_wrapper.cpp:0)
  >>>               CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_plugin_wrapper.cpp.o:(ARCorePluginWrapper::ARCorePluginWrapper())
  >>> referenced by arcore_plugin_wrapper.cpp:0 (../../../../src/main/cpp/jni\arcore_plugin_wrapper.cpp:0)
  >>>               CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_plugin_wrapper.cpp.o:(ARCorePluginWrapper::ARCorePluginWrapper())
  >>> referenced by arcore_plugin_wrapper.cpp:0 (../../../../src/main/cpp/jni\arcore_plugin_wrapper.cpp:0)
  >>>               CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_plugin_wrapper.cpp.o:(ARCorePluginWrapper::initialize_wrapper(_JNIEnv*, _jobject*, _jobject*, _jobject*))
  >>> referenced 5 more times

  ld: error: undefined symbol: ARCorePluginWrapper::godot_class
  >>> referenced by arcore_plugin_wrapper.cpp:0 (../../../../src/main/cpp/jni\arcore_plugin_wrapper.cpp:0)
  >>>               CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_plugin_wrapper.cpp.o:(ARCorePluginWrapper::initialize_wrapper(_JNIEnv*, _jobject*, _jobject*, _jobject*))
  >>> referenced by arcore_plugin_wrapper.cpp:0 (../../../../src/main/cpp/jni\arcore_plugin_wrapper.cpp:0)
  >>>               CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_plugin_wrapper.cpp.o:(ARCorePluginWrapper::initialize_wrapper(_JNIEnv*, _jobject*, _jobject*, _jobject*))
  >>> referenced by arcore_plugin_wrapper.cpp:0 (../../../../src/main/cpp/jni\arcore_plugin_wrapper.cpp:0)
  >>>               CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_plugin_wrapper.cpp.o:(ARCorePluginWrapper::uninitialize_wrapper(_JNIEnv*))
  >>> referenced 1 more times

  ld: error: undefined symbol: ARCorePluginWrapper::activity_class
  >>> referenced by arcore_plugin_wrapper.cpp:0 (../../../../src/main/cpp/jni\arcore_plugin_wrapper.cpp:0)
  >>>               CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_plugin_wrapper.cpp.o:(ARCorePluginWrapper::initialize_wrapper(_JNIEnv*, _jobject*, _jobject*, _jobject*))
  >>> referenced by arcore_plugin_wrapper.cpp:0 (../../../../src/main/cpp/jni\arcore_plugin_wrapper.cpp:0)
  >>>               CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_plugin_wrapper.cpp.o:(ARCorePluginWrapper::initialize_wrapper(_JNIEnv*, _jobject*, _jobject*, _jobject*))
  >>> referenced by arcore_plugin_wrapper.cpp:0 (../../../../src/main/cpp/jni\arcore_plugin_wrapper.cpp:0)
  >>>               CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_plugin_wrapper.cpp.o:(ARCorePluginWrapper::uninitialize_wrapper(_JNIEnv*))
  >>> referenced 1 more times

  ld: error: undefined symbol: ARCorePluginWrapper::godot_instance
  >>> referenced by arcore_plugin_wrapper.cpp:0 (../../../../src/main/cpp/jni\arcore_plugin_wrapper.cpp:0)
  >>>               CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_plugin_wrapper.cpp.o:(ARCorePluginWrapper::initialize_wrapper(_JNIEnv*, _jobject*, _jobject*, _jobject*))
  >>> referenced by arcore_plugin_wrapper.cpp:0 (../../../../src/main/cpp/jni\arcore_plugin_wrapper.cpp:0)
  >>>               CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_plugin_wrapper.cpp.o:(ARCorePluginWrapper::initialize_wrapper(_JNIEnv*, _jobject*, _jobject*, _jobject*))
  >>> referenced by arcore_plugin_wrapper.cpp:0 (../../../../src/main/cpp/jni\arcore_plugin_wrapper.cpp:0)
  >>>               CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_plugin_wrapper.cpp.o:(ARCorePluginWrapper::uninitialize_wrapper(_JNIEnv*))
  >>> referenced 7 more times

  ld: error: undefined symbol: ARCorePluginWrapper::activity
  >>> referenced by arcore_plugin_wrapper.cpp:0 (../../../../src/main/cpp/jni\arcore_plugin_wrapper.cpp:0)
  >>>               CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_plugin_wrapper.cpp.o:(ARCorePluginWrapper::initialize_wrapper(_JNIEnv*, _jobject*, _jobject*, _jobject*))
  >>> referenced by arcore_plugin_wrapper.cpp:0 (../../../../src/main/cpp/jni\arcore_plugin_wrapper.cpp:0)
  >>>               CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_plugin_wrapper.cpp.o:(ARCorePluginWrapper::initialize_wrapper(_JNIEnv*, _jobject*, _jobject*, _jobject*))
  >>> referenced by arcore_plugin_wrapper.cpp:0 (../../../../src/main/cpp/jni\arcore_plugin_wrapper.cpp:0)
  >>>               CMakeFiles/godot_arcore.dir/src/main/cpp/jni/arcore_plugin_wrapper.cpp.o:(ARCorePluginWrapper::uninitialize_wrapper(_JNIEnv*))
  >>> referenced 3 more times
  clang++: error: linker command failed with exit code 1 (use -v to see invocation)
  ninja: build stopped: subcommand failed.

Edit: After looking through your sample project Fredia I noticed that there is still a lot of configuration work on the plugin side needed to comply with the system you set and also to debug the bugs I encountered

[AThousandShips]

Just some comment style pointers

[BastiaanOlij]

Looks good to me.

Something to keep in mind once we put a template together, and possibly also for the documentation, is that with GDExtensions in Godot 4 it is imperative that extensions are compiled not just for Android, but also for the OS in which the developer is running the IDE, or the developer won't be able to actually write code that accesses the plugin. This may involve creating dummy plugins for the host OS just so the API is published to the editor.

It would be nice if the examples in godot-cpp could be enhanced to package up plugins in an AAR to show how cross platform plugins can be build.

[dsnopek]

It would be nice if the examples in godot-cpp could be enhanced

The example in godot-cpp was removed in favor of automated tests with the plan to eventually create a repo with several examples. This is something that could be added there! Although, there's already https://github.com/m4gr3d/Godot-Android-Samples with the one GDExtension example

[adamscott]

Discussed during the production meeting and we approve with the PR.

[akien-mga]

Thanks!

[m4gr3d]

Will wait on the documentation to be completed, to test both the documentation and plugin architecture itself Will migrate godot-android modules to 4.2 after that

@tokengamedev Early draft for the documentation update available in godotengine/godot-docs#7884