godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-05 22:09:56 +03:00
Code Issues Packages Projects Releases Wiki Activity

Update the Android documentation for Godot 4.2

Browse Source
This commit is contained in:
Fredia Huya-Kouadio
2023-09-03 19:46:14 -07:00
parent 0be715a949
commit 66ee5cb491
20 changed files with 607 additions and 194 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
tutorials/platform/android/android_in_app_purchases.rst
View File

@@ -1,17 +1,9 @@
:article_outdated: True
.. _doc_android_in_app_purchases:
Android in-app purchases
========================
Godot offers a first-party ``GodotGooglePlayBilling`` Android plugin compatible with Godot 3.2.2 and higher.
This plugin uses the `Google Play Billing library <https://developer.android.com/google/play/billing>`__
instead of the now deprecated AIDL IAP implementation. For details of how to migrate from the older
``GodotPaymentsV3``, see the migration guide: `Migrating from Godot 3.2.1 and lower (GodotPaymentsV3)`_.
If you learn better by looking at an example, you can find the demo project
`here <https://github.com/godotengine/godot-demo-projects/tree/master/mobile/android_iap>`__.
Godot offers a first-party ``GodotGooglePlayBilling`` Android plugin compatible with Godot 4 which uses the `Google Play Billing library <https://developer.android.com/google/play/billing>`_.
Usage
@@ -20,13 +12,9 @@ Usage
Getting started
***************
Make sure you have enabled and successfully set up :ref:`Android Custom Builds <doc_android_custom_build>`.
Make sure you have enabled and successfully set up :ref:`Android Gradle Builds <doc_android_gradle_build>`.
Follow the compiling instructions on the ``GodotGooglePlayBilling`` `github page <https://github.com/godotengine/godot-google-play-billing>`__.
.. note::
If you use a custom build you possibly have to put your own `godot-lib.***.release.aar` file in the `./godot-google-play-billing/libs/` folder.
Then put the files `./godot-google-play-billing/build/outputs/aar/GodotGooglePlayBilling.***.release.aar` and `./GodotGooglePlayBilling.gdap` into your project in the `res://android/plugins` folder.
The plugin should now show up in the Android export settings, where you can enable it.
@@ -35,7 +23,7 @@ The plugin should now show up in the Android export settings, where you can enab
Initialize the plugin
*********************
To use the ``GodotGooglePlayBilling`` API:
To use the ``GodotGooglePlayBilling`` API:
1. Obtain a reference to the ``GodotGooglePlayBilling`` singleton
2. Connect handlers for the plugin signals
@@ -70,7 +58,7 @@ Initialization example:
payment.startConnection()
else:
print("Android IAP support is not enabled. Make sure you have enabled 'Custom Build' and the GodotGooglePlayBilling plugin in your Android export settings! IAP will not work.")
print("Android IAP support is not enabled. Make sure you have enabled 'Gradle Build' and the GodotGooglePlayBilling plugin in your Android export settings! IAP will not work.")
The API must be in a connected state prior to use. The ``connected`` signal is sent
when the connection process succeeds. You can also use ``isReady()`` to determine if the plugin
@@ -123,7 +111,7 @@ Query user purchases
To retrieve a user's purchases, call the ``queryPurchases()`` function passing
a string with the type of SKU to query. The SKU type string should be
``"inapp"`` for normal in-app purchases or ``"subs"`` for subscriptions.
The ``query_purchases_response`` signal is sent with the result.
The ``query_purchases_response`` signal is sent with the result.
The signal has a single parameter: a :ref:`Dictionary <class_Dictionary>` with
a status code and either an array of purchases or an error message.
Only active subscriptions and non-consumed one-time purchases are
@@ -224,7 +212,7 @@ Purchase fields:
Check purchase state
********************
Check the ``purchase_state`` value of a purchase to determine if a
Check the ``purchase_state`` value of a purchase to determine if a
purchase was completed or is still pending.
PurchaseState values:
@@ -233,8 +221,8 @@ PurchaseState values:
# Matches Purchase.PurchaseState in the Play Billing Library
enum PurchaseState {
UNSPECIFIED,
PURCHASED,
UNSPECIFIED,
PURCHASED,
PENDING,
}
@@ -255,7 +243,7 @@ If your in-app item is not a one-time purchase but a consumable item (e.g. coins
multiple times, you can consume an item by calling ``consumePurchase()`` passing
the ``purchase_token`` value from the purchase dictionary.
Calling ``consumePurchase()`` automatically acknowledges a purchase.
Consuming a product allows the user to purchase it again, it will no longer appear
Consuming a product allows the user to purchase it again, it will no longer appear
in subsequent ``queryPurchases()`` calls unless it is repurchased.
Example use of ``consumePurchase()``:
@@ -347,11 +335,11 @@ The proration values are defined as:
::
enum SubscriptionProrationMode {
# Replacement takes effect immediately, and the remaining time
# Replacement takes effect immediately, and the remaining time
# will be prorated and credited to the user.
IMMEDIATE_WITH_TIME_PRORATION = 1,
# Replacement takes effect immediately, and the billing cycle remains the same.
# The price for the remaining period will be charged.
# Replacement takes effect immediately, and the billing cycle remains the same.
# The price for the remaining period will be charged.
# This option is only available for subscription upgrade.
IMMEDIATE_AND_CHARGE_PRORATED_PRICE,
# Replacement takes effect immediately, and the new price will be charged on
@@ -395,20 +383,3 @@ Example use of ``confirmPriceChange()``:
print("price_change_accepted")
elif response_id == BillingResponse.CANCELED:
print("price_change_canceled")
Migrating from Godot 3.2.1 and lower (GodotPaymentsV3)
------------------------------------------------------
The new ``GodotGooglePlayBilling`` API is not compatible with its predecessor ``GodotPaymentsV3``.
Changes
*******
- You need to enable the Custom Build option in your Android export settings and install
the ``GodotGooglePlayBilling`` plugin manually (see below for details)
- All purchases have to be acknowledged by your app. This is a
`requirement from Google <https://developer.android.com/google/play/billing/integrate#process>`__.
Purchases that are not acknowledged by your app will be refunded.
- Support for subscriptions
- Signals (no polling or callback objects)

240
tutorials/platform/android/android_library.rst Normal file
View File

@@ -0,0 +1,240 @@
.. _doc_android_library:
Godot Android Library
=====================
The Godot Engine for Android platforms is designed to be used as an `Android library <https://developer.android.com/studio/projects/android-library>`_.
This architecture enables several key features on Android platforms:
- Ability to integrate the Gradle build system within the Godot Editor, which provides the ability to leverage more components from the Android ecosystem such as libraries and tools
- Ability to make the engine portable and embeddable:
- Key in enabling the port of the Godot Editor to Android and mobile XR devices
- Key in allowing the integration and reuse of Godot's capabilities within existing codebase
Below we describe some of the use-cases and scenarios this architecture enables.
Using the Godot Android library
-------------------------------
The Godot Android library is packaged as an AAR archive file and hosted on `MavenCentral <https://central.sonatype.com/artifact/org.godotengine/godot>`_ along with `its documentation <https://javadoc.io/doc/org.godotengine/godot/latest/index.html>`_.
It is used to provide access to Godot APIs and capabilities on Android platforms for the following (non-exhaustive) use-cases.
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.
They are also Android libraries with a dependency on the Godot Android library
which is used for access to the Godot APIs and integration into the engine's lifecycle.
They offer similar features to the Godot Android library,
notably the ability to integrate with the Gradle (or other Android supported) build system,
and the ability to be portable and embeddable.
Access to Godot APIs and lifecycle grants Android plugins powerful capabilities
such as GDExtension which allows to update / mod the engine behavior as needed.
For more information, see :ref:`Godot Android plugins <doc_android_plugin>`.
Embedding Godot in existing Android projects
--------------------------------------------
The Godot Engine can be integrated within existing Android applications or libraries,
allowing developers to leverage mature and battle-tested code and libraries better suited to a specific task.
The hosting component is responsible for driving the engine lifecycle via Godot's Android APIs.
These APIs can also be used to provide bidirectional communication between the host and the running Godot instance allowing for greater control over the desired experience.
We showcase how this is done using a sample Android app that uses the Godot Engine as an embeddable Android view to render 3D GLTF models.
The `GLTF Viewer <https://github.com/m4gr3d/Godot-Android-Samples/tree/master/apps/gltf_viewer>`_ sample app uses an `Android RecyclerView component <https://developer.android.com/develop/ui/views/layout/recyclerview>`_ to create
and populate a list of GLTF items from `Kenney's Food Kit pack <https://kenney.nl/assets/food-kit>`_.
When an item on the list is selected, the app's logic interacts with the embedded Godot Engine to render the selected GLTF item as a 3D model.
.. image:: img/gltf_viewer_sample_app_screenshot.webp
The sample app source code can be found `on GitHub <https://github.com/m4gr3d/Godot-Android-Samples/tree/master/apps/gltf_viewer>`_.
Follow the instructions on `its README <https://github.com/m4gr3d/Godot-Android-Samples/blob/master/apps/gltf_viewer/README.md>`_ to build and install it.
Below we break-down the steps used to create the GLTF Viewer app.
.. warning::
Currently only a single instance of the Godot Engine is supported per process.
You can configure the process the Android Activity runs under using the `android:process attribute <https://developer.android.com/guide/topics/manifest/activity-element#proc>`_.
.. warning::
Automatic resizing / orientation configuration events are not supported and may cause a crash.
You can disable those events:
- By locking to a specific orientation using the `android:screenOrientation attribute <https://developer.android.com/guide/topics/manifest/activity-element#screen>`_.
- By declaring that the Activity will handle these configuration events using the `android:configChanges attribute <https://developer.android.com/guide/topics/manifest/activity-element#config>`_.
1. Create the Android app
^^^^^^^^^^^^^^^^^^^^^^^^^
.. note::
The Android sample app was created using `Android Studio <https://developer.android.com/studio>`_
and using `Gradle <https://developer.android.com/build>`_ 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 <https://central.sonatype.com/artifact/org.godotengine/godot>`_
- 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:
.. code-block:: kotlin
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.
- If your build system does not support including hidden directories, you can `configure the Godot project to not use hidden directories <https://docs.godotengine.org/en/stable/classes/class_projectsettings.html#class-projectsettings-property-application-config-use-hidden-project-data-directory>`_ by deselecting ``Project Settings... > Application > Config > Use Hidden Project Data Directory``.
.. code-block:: groovy
android {
defaultConfig {
// The default ignore pattern for the 'assets' directory includes hidden files and
// directories which are used by Godot projects, so we override it with the following.
aaptOptions {
ignoreAssetsPattern "!.svn:!.git:!.gitignore:!.ds_store:!*.scc:<dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"
}
...
- Create / update the application's Activity that will be hosting the Godot Engine instance. For the sample app, this is `MainActivity <https://github.com/m4gr3d/Godot-Android-Samples/blob/master/apps/gltf_viewer/src/main/java/fhuyakou/godot/app/android/gltfviewer/MainActivity.kt>`_
- The host Activity should implement the `GodotHost interface <https://github.com/godotengine/godot/blob/master/platform/android/java/lib/src/org/godotengine/godot/GodotHost.java>`_
- The sample app uses `Fragments <https://developer.android.com/guide/fragments>`_ to organize its UI, so it uses `GodotFragment <https://github.com/godotengine/godot/blob/master/platform/android/java/lib/src/org/godotengine/godot/GodotFragment.java>`_, a fragment component provided by the Godot Android library to automatically host and manage the Godot Engine instance.
.. code-block:: kotlin
private var godotFragment: GodotFragment? = null
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
val currentGodotFragment = supportFragmentManager.findFragmentById(R.id.godot_fragment_container)
if (currentGodotFragment is GodotFragment) {
godotFragment = currentGodotFragment
} else {
godotFragment = GodotFragment()
supportFragmentManager.beginTransaction()
.replace(R.id.godot_fragment_container, godotFragment!!)
.commitNowAllowingStateLoss()
}
...
.. note::
The Godot Android library also provide `GodotActivity <https://github.com/godotengine/godot/blob/master/platform/android/java/lib/src/org/godotengine/godot/GodotActivity.kt>`_, an Activity component that can be extended to automatically host and manage the Godot Engine instance.
Alternatively, applications can directly create a `Godot <https://github.com/godotengine/godot/blob/master/platform/android/java/lib/src/org/godotengine/godot/Godot.kt>`_ instance, host and manage it themselves.
- Using `GodotHost#getHostPlugins(...) <https://github.com/m4gr3d/Godot-Android-Samples/blob/0e3440f357f8be5b4c63a4fe75766793199a99d0/apps/gltf_viewer/src/main/java/fhuyakou/godot/app/android/gltfviewer/MainActivity.kt#L55>`_, the sample app creates a `runtime GodotPlugin instance <https://github.com/m4gr3d/Godot-Android-Samples/blob/master/apps/gltf_viewer/src/main/java/fhuyakou/godot/app/android/gltfviewer/AppPlugin.kt>`_ that's used to send :ref:`signals <doc_signals>` to the ``gdscript`` logic
- The runtime ``GodotPlugin`` can also be used by ``gdscript`` logic to access JVM methods. For more information, see :ref:`Godot Android plugins <doc_android_plugin>`.
- Add any additional logic that will be used by your application
- For the sample app, this includes adding the `ItemsSelectionFragment fragment <https://github.com/m4gr3d/Godot-Android-Samples/blob/master/apps/gltf_viewer/src/main/java/fhuyakou/godot/app/android/gltfviewer/ItemsSelectionFragment.kt>`_ (and related classes), a fragment used to build and show the list of GLTF items
- Open the ``AndroidManifest.xml`` file, and configure the orientation if needed using the `android:screenOrientation attribute <https://developer.android.com/guide/topics/manifest/activity-element#screen>`_
- If needed, disable automatic resizing / orientation configuration changes using the `android:configChanges attribute <https://developer.android.com/guide/topics/manifest/activity-element#config>`_
.. code-block:: xml
<activity android:name=".MainActivity"
android:screenOrientation="fullUser"
android:configChanges="orientation|screenSize|smallestScreenSize|screenLayout"
android:exported="true">
...
</activity>
2. Create the Godot project
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. note::
On Android, Godot's project files are exported to the ``assets`` directory of the generated ``apk`` binary.
We use that info 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 <https://docs.godotengine.org/en/stable/tutorials/export/exporting_projects.html#pck-versus-zip-pack-file-formats>`_
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() <https://github.com/godotengine/godot/blob/6916349697a4339216469e9bf5899b983d78db07/platform/android/java/lib/src/org/godotengine/godot/GodotHost.java#L45>`_.
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
- See the sampple app's `Godot project <https://github.com/m4gr3d/Godot-Android-Samples/tree/master/apps/gltf_viewer/src/main/assets>`_ for reference
- Configure the Godot project as desired
- Make sure the `orientation <https://docs.godotengine.org/en/stable/classes/class_projectsettings.html#class-projectsettings-property-display-window-handheld-orientation>`_ set for the Godot project matches the one set in the Android app's manifest
- For Android, make sure `textures/vram_compression/import_etc2_astc <https://docs.godotengine.org/en/stable/classes/class_projectsettings.html#class-projectsettings-property-rendering-textures-vram-compression-import-etc2-astc>`_ is set to `true`
- Update the Godot project script logic as needed
- For the sample app, the `script logic <https://github.com/m4gr3d/Godot-Android-Samples/blob/master/apps/gltf_viewer/src/main/assets/main.gd>`_ 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.
.. code-block:: gdscript
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:
print("App plugin is available")
# Signal fired from the app logic to update the gltf model being shown
appPlugin.connect("show_gltf", _load_gltf)
else:
print("App plugin is not available")
# Load the gltf model specified by the given path
func _load_gltf(gltf_path: String):
if current_gltf_node != null:
remove_child(current_gltf_node)
current_gltf_node = load(gltf_path).instantiate()
add_child(current_gltf_node)
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 <https://developer.android.com/studio/debug/logcat>`_ to investigate any errors or crashes.
For reference, check the `build and install instructions <https://github.com/m4gr3d/Godot-Android-Samples/blob/master/apps/gltf_viewer/README.md>`_ for the GLTF Viewer sample app.

422
tutorials/platform/android/android_plugin.rst
View File

@@ -1,165 +1,369 @@
:article_outdated: True
.. _doc_android_plugin:
Creating Android plugins
========================
Godot 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.
by tapping into the functionality provided by Android platforms 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
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 plugin
--------------
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 and in Godot 4.0, the previous system was fully deprecated and removed.
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.
**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.
As a prerequisite, make sure you understand how to set up a :ref:`custom build environment<doc_android_custom_build>` for Android.
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.
At its core, a Godot Android plugin is a `Android archive library <https://developer.android.com/studio/projects/android-library#aar-contents>`_ (*aar* archive file)
with the following caveats:
v2 Architecture
^^^^^^^^^^^^^^^
- 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 <https://godotengine.org/download>`_.
- The library must include a specifically configured ``<meta-data>`` tag in its manifest file.
.. note::
Building an Android plugin
^^^^^^^^^^^^^^^^^^^^^^^^^^
Godot Android plugin leverages the :ref:`Gradle build system <doc_android_gradle_build>`.
**Prerequisite:** `Android Studio <https://developer.android.com/studio>`_ is strongly recommended as the IDE to use to create Android plugins.
The instructions below assumes that you're using Android Studio.
1. Follow `these instructions <https://developer.android.com/studio/projects/android-library>`__ to create an Android library module for your plugin.
Building on the previous architecture, Android plugins continue to be derived from the
`Android archive library <https://developer.android.com/studio/projects/android-library#aar-contents>`_.
2. Add the Godot engine library as a dependency to your plugin module:
At its core, a Godot Android plugin v2 is an Android library with a dependency on the :ref:`Godot Android library <doc_android_library>`,
and a custom Android library manifest.
- Download the Godot engine library (``godot-lib.<version>.<status>.aar``) from the `Godot download page <https://godotengine.org/download>`_ (e.g: ``godot-lib.4.0.stable.aar``).
- Follow `these instructions <https://developer.android.com/studio/projects/android-library#AddDependency>`__ to add
the Godot engine library as a dependency for your plugin.
- In the plugin module's ``build.gradle`` file, replace ``implementation`` with ``compileOnly`` for the dependency line for the Godot engine library.
This architecture allows Android plugins to extend the functionality of the engine with:
3. 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.
- Android platform APIs
- Android libraries
- Kotlin and Java libraries
- Native libraries (via JNI)
- GDExtension libraries
4. Update the plugin ``AndroidManifest.xml`` file:
Each plugin has an init class extending from the `GodotPlugin class <https://github.com/godotengine/godot/blob/0a7f75ec7b465604b6496c8f5f1d638aed250d6d/platform/android/java/lib/src/org/godotengine/godot/plugin/GodotPlugin.java#L80>`_
which is provided by the :ref:`Godot Android library <doc_android_library>`.
- Open the plugin ``AndroidManifest.xml`` file.
- Add the ``<application></application>`` tag if it's missing.
- In the ``<application>`` tag, add a ``<meta-data>`` tag setup as follow::
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 <https://docs.godotengine.org/en/stable/tutorials/plugins/editor/installing_plugins.html>`_.
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 <https://github.com/m4gr3d/Godot-Android-Plugin-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 <https://developer.android.com/studio/projects/android-library>`_
2. Add the Godot Android library as a dependency by updating the module's ``gradle`` `build file <https://github.com/m4gr3d/Godot-Android-Plugin-Template/blob/main/plugin/build.gradle.kts#L42>`_.::
dependencies {
implementation("org.godotengine:godot:4.2.0.stable")
}
The Godot Android library is `hosted on MavenCentral <https://central.sonatype.com/artifact/org.godotengine/godot>`_, and updated for each release.
3. Create `GodotAndroidPlugin <https://github.com/m4gr3d/Godot-Android-Plugin-Template/blob/a01286b4cb459133bf07b11dfabdfd3980268797/plugin/src/main/java/org/godotengine/plugin/android/template/GodotAndroidPlugin.kt#L10>`_, an init class for the plugin extending `GodotPlugin <https://github.com/godotengine/godot/blob/0a7f75ec7b465604b6496c8f5f1d638aed250d6d/platform/android/java/lib/src/org/godotengine/godot/plugin/GodotPlugin.java#L80>`_.
- If the plugin exposes Kotlin or Java methods to be called from GDScript, they must be annotated with `@UsedByGodot <https://github.com/godotengine/godot/blob/0a7f75ec7b465604b6496c8f5f1d638aed250d6d/platform/android/java/lib/src/org/godotengine/godot/plugin/UsedByGodot.java#L45>`_. 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 <https://docs.godotengine.org/en/stable/getting_started/step_by_step/signals.html>`_, the init class must return the set of signals used by overriding `GodotPlugin::getPluginSignals() <https://github.com/godotengine/godot/blob/fa3428ff25bc577d2a3433090478a6d615567056/platform/android/java/lib/src/org/godotengine/godot/plugin/GodotPlugin.java#L302>`_. To emit signals, the plugin can use the `GodotPlugin::emitSignal(...) method <https://github.com/godotengine/godot/blob/0a7f75ec7b465604b6496c8f5f1d638aed250d6d/platform/android/java/lib/src/org/godotengine/godot/plugin/GodotPlugin.java#L317>`_.
4. Update the plugin ``AndroidManifest.xml`` `file <https://github.com/m4gr3d/Godot-Android-Plugin-Template/blob/main/plugin/src/main/AndroidManifest.xml>`_ with the following meta-data::
<meta-data
android:name="org.godotengine.plugin.v1.[PluginName]"
android:name="org.godotengine.plugin.v2.[PluginName]"
android:value="[plugin.init.ClassFullName]" />
Where ``PluginName`` is the name of the plugin, and ``plugin.init.ClassFullName`` is the full name (package + class name) of the plugin loading class.
5. Add the remaining logic for your plugin and run the ``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.
Where:
It's recommended that the ``aar`` filename matches the following pattern: ``[PluginName]*.aar`` where ``PluginName`` is the name of the plugin in PascalCase (e.g.: ``GodotPayment.release.aar``).
- ``PluginName`` is the name of the plugin
- ``plugin.init.ClassFullName`` is the full name (package + class name) of the plugin loading class (e.g: ``org.godotengine.plugin.android.template.GodotAndroidPlugin``).
6. Create a Godot Android Plugin configuration file to help the system detect and load your plugin:
5. Create the `EditorExportPlugin configuration <https://github.com/m4gr3d/Godot-Android-Plugin-Template/tree/main/plugin/export_scripts_template>`_ to package the plugin. The steps used to create the configuration can be seen in the `Packaging a v2 Android plugin`_ section.
- The configuration file extension must be ``gdap`` (e.g.: ``MyPlugin.gdap``).
- The configuration file format is as follow::
[config]
Building a v2 Android plugin with GDExtension capabilities
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
name="MyPlugin"
binary_type="local"
binary="MyPlugin.aar"
Similar to GDNative support in v1 Android plugins, v2 Android plugins support the ability to integrate GDExtension capabilities.
[dependencies]
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 <https://github.com/m4gr3d/GDExtension-Android-Plugin-Template#readme>`_
to set up your own Godot Android plugin project.
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=["https://repo.mycompany.com/maven2"]
The ``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**:
- If **binary_type** is ``local``, then this should be the filepath of the plugin ``aar`` file.
- The filepath can be relative (e.g.: ``MyPlugin.aar``) in which case it's relative to the ``res://android/plugins`` directory.
- The filepath can be absolute: ``res://some_path/MyPlugin.aar``.
- If **binary_type** is ``remote``, then this should be a declaration for a `remote gradle binary <https://developer.android.com/studio/build/dependencies#dependency-types>`_ (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
Migrating a v1 Android plugin to v2
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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 ``res://android/plugins`` directory.
Use the following steps if you have a v1 Android plugin you want to migrate to v2:
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.
1. Update the plugin's manifest file:
In order to allow GDScript to communicate with your Java Singleton, you must annotate your function with ``@UsedByGodot``. The name called from GDScript must match the function name exactly. There is **no** coercing ``snake_case`` to ``camelCase``.
- Change the ``org.godotengine.plugin.v1`` prefix to ``org.godotengine.plugin.v2``
.. image:: img/android_export_preset_plugins_section.png
2. Update the Godot Android library build dependency:
From your script::
- You can continue using the ``godot-lib.<version>.<status>.aar`` binary from `Godot's download page <https://godotengine.org/download>`_ 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 <https://docs.godotengine.org/en/stable/tutorials/plugins/editor/making_plugins.html#creating-a-plugin>`_.
1. Add the plugin output binaries within the plugin directory (e.g: in ``addons/<plugin_name>/``)
2. Add the `tool script <https://docs.godotengine.org/en/stable/tutorials/plugins/editor/making_plugins.html#the-script-file>`_ for the export functionality within the plugin directory (e.g: in ``addons/<plugin_name>/``)
- The created script must be ``@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 <https://docs.godotengine.org/en/stable/classes/class_editorexportplugin.html>`_ most relevant to use in this tool script:
- `_supports_platform <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-supports-platform>`_: returns ``true`` if the plugin supports the given platform. For Android plugins, this must return ``true`` when ``platform`` is `EditorExportPlatformAndroid <https://docs.godotengine.org/en/stable/classes/class_editorexportplatformandroid.html>`_
- `_get_android_libraries <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-libraries>`_: retrieve the local paths of the Android libraries binaries (AAR files) provided by the plugin
- `_get_android_dependencies <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-dependencies>`_: retrieve the set of Android maven dependencies (e.g: `org.godot.example:my-plugin:0.0.0`) provided by the plugin
- `_get_android_dependencies_maven_repos <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-dependencies-maven-repos>`_: retrieve the urls of the maven repos for the android dependencies provided by ``_get_android_dependencies``
- `_get_android_manifest_activity_element_contents <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-manifest-activity-element-contents>`_: update the contents of the `<activity>` element in the generated Android manifest
- `_get_android_manifest_application_element_contents <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-manifest-application-element-contents>`_: update the contents of the `<application>` element in the generated Android manifest
- `_get_android_manifest_element_contents <https://docs.godotengine.org/en/latest/classes/class_editorexportplugin.html#class-editorexportplugin-method-get-android-manifest-element-contents>`_: update the contents of the `<manifest>` element in the generated Android manifest
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 <https://github.com/m4gr3d/Godot-Android-Plugin-Template/tree/main/plugin/export_scripts_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:
.. code-block:: none
export_scripts_template/
|
+--export_plugin.gd # export plugin tool script
|
+--plugin.cfg # plugin INI file
Packaging a v2 Android plugin with GDExtension capabilities
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For GDExtension, we follow the same steps as for `Packaging a v2 Android plugin`_ and add the `GDExtension config file <https://docs.godotengine.org/en/stable/tutorials/scripting/gdextension/gdextension_cpp_example.html#using-the-gdextension-module>`_ in
the same location as ``plugin.cfg``.
For reference, here is the `folder structure for the GDExtension Android plugin project template <https://github.com/m4gr3d/GDExtension-Android-Plugin-Template/tree/main/plugin/export_scripts_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:
.. code-block:: none
export_scripts_template/
|
+--export_plugin.gd # export plugin tool script
|
+--plugin.cfg # plugin INI file
|
+--plugin.gdextension # GDExtension config file
Here is what the ``plugin.gdextension`` config file should look like::
[configuration]
entry_symbol = "plugin_library_init"
compatibility_minimum = "4.2"
android_aar_plugin = true
[libraries]
android.debug.arm64 = "res://addons/GDExtensionAndroidPluginTemplate/bin/debug/arm64-v8a/libGDExtensionAndroidPluginTemplate.so"
android.release.arm64 = "res://addons/GDExtensionAndroidPluginTemplate/bin/release/arm64-v8a/libGDExtensionAndroidPluginTemplate.so"
...
Of note is the ``android_aar_plugin`` field that specifies this GDExtension module is provided as part of a v2 Android plugin.
During the export process, this will indicate to the Godot Editor that the GDExtension native shared libraries are exported by the Android plugin AAR binaries.
For GDExtension Android plugins, the plugin init class must override `GodotPlugin::getPluginGDExtensionLibrariesPaths() <https://github.com/godotengine/godot/blob/0a7f75ec7b465604b6496c8f5f1d638aed250d6d/platform/android/java/lib/src/org/godotengine/godot/plugin/GodotPlugin.java#L277>`_,
and return the paths to the bundled GDExtension libraries config files (``*.gdextension``).
The paths must be relative to the Android library's ``assets`` directory.
At runtime, the plugin will provide these paths to the Godot engine which will use them to load and initialize the bundled GDExtension libraries.
Using a v2 Android plugin
-------------------------
.. note::
- Godot 4.2 or higher is required
- v2 Android plugin requires the use of the `Gradle build process <https://docs.godotengine.org/en/stable/classes/class_editorexportplatformandroid.html#class-editorexportplatformandroid-property-gradle-build-use-gradle-build>`_.
- The provided github project templates include demo Godot projects for quick testing.
1. Copy the plugin's output directory (``addons/<plugin_name>``) to the target Godot project's directory
2. Open the project in the Godot Editor; the Editor should detect the plugin
3. Navigate to ``Project`` -> ``Project Settings...`` -> ``Plugins``, and ensure the plugin is enabled
4. Install the Godot Android build template by clicking on ``Project`` -> ``Install Android Build Template...``
5. Navigate to ``Project`` -> ``Export...``
6. In the ``Export`` window, create an ``Android export preset``
7. In the ``Android export preset``, scroll to ``Gradle Build`` and set ``Use Gradle Build`` to ``true``
8. Update the project's scripts as needed to access the plugin's functionality. For example::
if Engine.has_singleton("MyPlugin"):
var singleton = Engine.get_singleton("MyPlugin")
print(singleton.myPluginFunction("World"))
var singleton = Engine.get_singleton("MyPlugin")
print(singleton.myPluginFunction("World"))
9. Connect an Android device to your machine and run the project on it
Bundling GDExtension resources
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Using a v2 Android plugin as an Android library
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
An Android plugin can define and provide C/C++ GDExtension resources, either to provide and/or access functionality from the game logic.
The GDExtension resources can be bundled within the plugin ``aar`` file which simplifies the distribution and deployment process:
Since they are also Android libraries, Godot v2 Android plugins can be stripped from their ``EditorExportPlugin`` packaging and provided as raw ``AAR`` binaries for use as libraries alongside the :ref:`Godot Android library <doc_android_library>` by Android apps.
- The shared libraries (``.so``) for the defined GDExtension libraries will be automatically bundled by the ``aar`` build system.
- Godot ``*.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]/``.
For GDExtension libraries, the plugin singleton object must override the ``org.godotengine.godot.plugin.GodotPlugin::getPluginGDNativeLibrariesPaths()`` method,
and return the paths to the bundled GDExtension libraries config files (``*.gdextension``). 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 GDExtension libraries.
If targetting this use-case, make sure to include additional instructions for how the ``AAR`` binaries should be included (e.g: custom additions to the Android app's manifest).
Reference implementations
^^^^^^^^^^^^^^^^^^^^^^^^^
-------------------------
- `Godot Oculus Mobile plugin <https://github.com/GodotVR/godot_oculus_mobile>`_
- `Bundled gdnative resources <https://github.com/GodotVR/godot_oculus_mobile/tree/master/plugin/src/main/assets/addons/godot_ovrmobile>`_
- `Godot Google Play Billing plugin <https://github.com/godotengine/godot-google-play-billing>`_
- `Godot Android Plugins Samples <https://github.com/m4gr3d/Godot-Android-Samples/tree/master/plugins>`_
- `Godot Android Plugin Template <https://github.com/m4gr3d/Godot-Android-Plugin-Template>`_
- `GDExtension Android Plugin Template <https://github.com/m4gr3d/GDExtension-Android-Plugin-Template>`_
- `Godot OpenXR Loaders <https://github.com/GodotVR/godot_openxr_loaders>`_
Troubleshooting
---------------
Tips and Guidelines
-------------------
Simplify access to the exposed Java / Kotlin APIs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To make it easier to access the exposed Java / Kotlin APIs in the Godot Editor, it's recommended to
provide one (or multiple) gdscript wrapper class(es) for your plugin users to interface with.
For example::
class_name PluginInterface extends Object
## Interface used to access the functionality provided by this plugin.
var _plugin_name = "GDExtensionAndroidPluginTemplate"
var _plugin_singleton
func _init():
if Engine.has_singleton(_plugin_name):
_plugin_singleton = Engine.get_singleton(_plugin_name)
else:
printerr("Initialization error: unable to access the java logic")
## Print a 'Hello World' message to the logcat.
func helloWorld():
if _plugin_singleton:
_plugin_singleton.helloWorld()
else:
printerr("Initialization error")
Support using the gdextension functionality in the Godot Editor
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If planning to use the gdextension functionality in the Godot Editor, it is recommended that the
gdextension's native binaries are compiled not just for Android, but also for the OS onto which
developers / users intend to run the Godot Editor. Not doing so may prevent developers /
users from writing code that accesses the plugin from within the Godot Editor.
This may involve creating dummy plugins for the host OS just so the API is published to the
editor. You can use the [godot-cpp-template](https://github.com/godotengine/godot-cpp-template)
github template for reference on how to do so.
Godot crashes upon load
^^^^^^^^^^^^^^^^^^^^^^^

BIN
tutorials/platform/android/img/android_export_preset_plugins_section.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 46 KiB

BIN
tutorials/platform/android/img/gltf_viewer_sample_app_screenshot.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 23 KiB

9
tutorials/platform/android/index.rst
View File

@@ -1,11 +1,10 @@
:article_outdated: True
Android plugins
===============
Android
=======
.. toctree::
:maxdepth: 1
:name: toc-tutorials-plugins-android
:name: toc-tutorials-android
android_library
android_plugin
android_in_app_purchases