Creating Android plugins¶
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:
In-game soft & hard currencies
Leaderboards and scores
User support & feedback
Posting to Facebook, Twitter, etc.
While introduced in Godot 3.2, the Android plugin system got a significant architecture update starting with Godot 3.2.2.
The new plugin system is backward-incompatible with the previous one, but both systems are kept functional in future releases of the 3.2.x branch.
Since we previously did not version the Android plugin systems, the new one is now labelled
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.
As a prerequisite, make sure you understand how to set up a custom build environment for Android.
At its core, a Godot Android plugin is a Android archive library (aar archive file) with the following caveats:
The library must have a dependency on the Godot engine library (
godot-lib.<version>.<status>.aar). A stable version is made available for each Godot release on the Godot download page.
The library must include a specifically configured
<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.
Follow these instructions to create an Android library module for your plugin.
Add the Godot engine library as a dependency to your plugin module:
Download the Godot engine library (
godot-lib.<version>.<status>.aar) from the Godot download page (e.g.:
Follow these instructions to add the Godot engine library as a dependency for your plugin.
In the plugin module's
compileOnlyfor the dependency line for the Godot engine library.
Create a new class in the plugin module and make sure it extends
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.
Update the plugin
Open the plugin
<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]" />
PluginNameis the name of the plugin, and
plugin.init.ClassFullNameis the full name (package + class name) of the plugin loading class.
Add the remaining logic for your plugin and run the
gradlew buildcommand to generate the plugin's
aarfile. The build will likely generate both a
aarfiles. Depending on your need, pick only one version (usually the
releaseone) which to provide your users with.
It's recommended that the
aarfilename matches the following pattern:
PluginNameis the name of the plugin in PascalCase (e.g.:
Create a Godot Android Plugin configuration file to help the system detect and load your plugin:
The configuration file extension must be
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"]
configsection and fields are required and defined as follow:
name: name of the plugin.
binary_type: can be either
remote. The type affects the binary field.
If binary_type is
local, then this should be the filepath of the plugin
The filepath can be relative (e.g.:
MyPlugin.aar) in which case it's relative to the
The filepath can be absolute:
If binary_type is
remote, then this should be a declaration for a remote gradle binary (e.g.:
dependenciessection and fields are optional and defined as follow:
local: contains a list of filepaths to the local
.aarbinary files the plugin depends on. Similarly to the
binaryfield (when the
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¶
Move the plugin configuration file (e.g.:
MyPlugin.gdap) and, if any, its local binary (e.g.:
MyPlugin.aar) and dependencies to the Godot project's
The Godot editor will automatically parse all
.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¶
An Android plugin can define and provide C/C++ GDNative resources, either to provide and/or access functionality from the game logic.
The GDNative resources can be bundled within the plugin
aar file which simplifies the distribution and deployment process:
The shared libraries (
.so) for the defined GDNative libraries will be automatically bundled by the
*.gdnsresource files must be manually defined in the plugin
assetsdirectory. The recommended path for these resources relative to the
assetsdirectory should be:
For GDNative libraries, the plugin singleton object must override the
and return the paths to the bundled GDNative libraries config files (
*.gdnlib). The paths must be relative to the
At runtime, the plugin will provide these paths to Godot core which will use them to load and initialize the bundled GDNative libraries.
Godot crashes upon load¶
adb logcat for possible problems, then:
Check that the methods exposed by the plugin used the following Java types:
More complex datatypes are not supported for now.