Creating Android plugins

Introduction

Android plugins are powerful tools to extend the capabilities of the Godot engine by tapping into the functionality provided by the Android platform and ecosystem. Mobile gaming monetization is one such example since it requires features and capabilities that don’t belong to the core feature set of a game engine:

• Analytics
• In-app purchases
• Receipt validation
• Install tracking
• Ads
• Video ads
• Cross-promotion
• In-game soft & hard currencies
• Promo codes
• A/B testing
• Login
• Cloud saves
• Leaderboards and scores
• User support & feedback
• Posting to Facebook, Twitter, etc.
• Push notifications

  Android plugin

  v1 and is the starting point for the modern Godot Android ecosystem. Note: In Godot 4.0, the previous system will be fully deprecated and removed. custom build environment for Android. Android archive library (aar archive file) with the following caveats:
• godot-lib.<version>.<status>.aar). A stable version is made available for each Godot release on the Godot download page.
• <meta-data> tag in its manifest file.

  Building an Android plugin

  Prerequisite: Android Studio is strongly recommended as the IDE to use to create Android plugins. The instructions below assumes that you’re using Android Studio.

1. these instructions to create an Android library module for your plugin.
2. Add the Godot engine library as a dependency to your plugin module:

   • godot-lib.<version>.<status>.aar) from the Godot download page (e.g.: godot-lib.3.4.2.stable.release.aar).

• these instructions to add the Godot engine library as a dependency for your plugin.
• build.gradle file, replace implementation with compileOnly for the dependency line for the Godot engine library.

1. org.godotengine.godot.plugin.GodotPlugin. At runtime, it will be used to instantiate a singleton object that will be used by the Godot engine to load, initialize and run the plugin.
2. AndroidManifest.xml file:

   • AndroidManifest.xml file.

• <application></application> tag if it’s missing.
• <application> tag, add a <meta-data> tag setup as follow:

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

PluginName is the name of the plugin, and plugin.init.ClassFullName is the full name (package + class name) of the plugin loading class.

1. gradlew build command to generate the plugin’s aar file. The build will likely generate both a debug and release aar files. Depending on your need, pick only one version (usually the release one) which to provide your users with. aar filename matches the following pattern: [PluginName]*.aar where PluginName is the name of the plugin in PascalCase (e.g.: GodotPayment.release.aar).
2. Create a Godot Android Plugin configuration file to help the system detect and load your plugin:

   • gdap (e.g.: MyPlugin.gdap).

• The configuration file format is as follow:

[config]name="MyPlugin"binary_type="local"binary="MyPlugin.aar"[dependencies]local=["local_dep1.aar", "local_dep2.aar"]remote=["example.plugin.android:remote-dep1:0.0.1", "example.plugin.android:remote-dep2:0.0.1"]custom_maven_repos=["http://repo.mycompany.com/maven2"]

config section and fields are required and defined as follow:

• name: name of the plugin.
• binary_type: can be either local or remote. The type affects the binary field.

• binary:

• binary_type is local, then this should be the filepath of the plugin aar file.

• MyPlugin.aar) in which case it’s relative to the res://android/plugins directory.

• res://some_path/MyPlugin.aar.
• binary_type is remote, then this should be a declaration for a remote gradle binary (e.g.: org.godot.example:my-plugin:0.0.0).

The `dependencies` section and fields are optional and defined as follow:-   **local**: contains a list of filepaths to the local `.aar` binary files the plugin depends on. Similarly to the `binary` field (when the `binary_type` is `local`), the local binaries' filepaths can be relative or absolute.-   **remote**: contains a list of remote binary gradle dependencies for the plugin.-   **custom\_maven\_repos**: contains a list of URLs specifying the custom maven repositories required for the plugin's dependencies.

Loading and using an Android plugin

MyPlugin.gdap) and, if any, its local binary (e.g.: MyPlugin.aar) and dependencies to the Godot project’s res://android/plugins directory. .gdap files in the res://android/plugins directory and show a list of detected and toggleable plugins in the Android export presets window under the Plugins section. From your script:

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

Bundling GDNative resources

aar file which simplifies the distribution and deployment process:

• .so) for the defined GDNative libraries will be automatically bundled by the aar build system.
• *.gdnlib and *.gdns resource files must be manually defined in the plugin assets directory. The recommended path for these resources relative to the assets directory should be: godot/plugin/v1/[PluginName]/. org.godotengine.godot.plugin.GodotPlugin::getPluginGDNativeLibrariesPaths() method, and return the paths to the bundled GDNative libraries config files (*.gdnlib). The paths must be relative to the assets directory. At runtime, the plugin will provide these paths to Godot core which will use them to load and initialize the bundled GDNative libraries.

  Reference implementations

• Godot Oculus Mobile plugin - Bundled gdnative resources
• Godot Google Play Billing plugin

  Troubleshooting

  Godot crashes upon load

  adb logcat for possible problems, then:
• void, boolean, int, float, java.lang.String, org.godotengine.godot.Dictionary, int[], byte[], float[], java.lang.String[].
• More complex datatypes are not supported for now.