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

Merge branch 'master' into 3.2

Browse Source
This commit is contained in:
Rémi Verschelde
2020-05-20 15:08:42 +02:00
parent 568dbeb72e cc52414fec
commit 10f20b00cb
245 changed files with 2980 additions and 1789 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
tutorials/plugins/android/android_plugin.rst
View File

@@ -6,10 +6,10 @@ Creating Android plugins (Godot 3.2.2+)
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.
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
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
@@ -38,7 +38,7 @@ While introduced in Godot 3.2.0, the Android plugin system got a significant arc
As a prerequisite, make sure you understand how to set up a :ref:`custom build environment<doc_android_custom_build>` for Android.
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)
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:
- The library must have a dependency on the Godot engine library (``godot-lib.x.y.aar``). A stable version is made available for each Godot release.
@@ -48,7 +48,7 @@ with the following caveats:
Building a Android plugin
^^^^^^^^^^^^^^^^^^^^^^^^^
**Prerequisite:** `Android Studio <https://developer.android.com/studio>`_ is strongly recommended as the IDE to use to create Android plugins.
**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.
@@ -72,18 +72,19 @@ The instructions below assumes that you're using Android Studio.
- Add the ``<application></application>`` tag if it's missing.
- In the ``<application>`` tag, add a ``<meta-data>`` tag setup as follow::
<meta-data
android:name="org.godotengine.plugin.v1.[PluginName]"
<meta-data
android:name="org.godotengine.plugin.v1.[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.
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.
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``).
6. Create a Godot Android Plugin configuration file to help the system detect and load your plugin:
- The configuration file extension must be ``gdap`` (e.g.: ``MyPlugin.gdap``).
@@ -123,9 +124,8 @@ The instructions below assumes that you're using Android Studio.
- **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 a Android plugin
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -136,7 +136,6 @@ The Godot editor will automatically parse all ``.gdap`` files in the ``res://and
.. image:: img/android_export_preset_plugins_section.png
From your script:
.. code::
@@ -151,12 +150,12 @@ Bundling GDNative resources
A 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 ``aar`` build system.
- The shared libraries (``.so``) for the defined GDNative 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.
- 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 GDNative libraries, the plugin singleton object must override the ``org.godotengine.godot.plugin.GodotPlugin::getPluginGDNativeLibrariesPaths()`` method,
For GDNative libraries, the plugin singleton object must override the ``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.