Update the Android documentation for Godot 4.2

_tools/redirects/redirects.csv

@@ -130,7 +130,7 @@ source,destination
 /getting_started/workflow/best_practices/scene_organization.html,/tutorials/best_practices/scene_organization.html
 /getting_started/workflow/best_practices/scenes_versus_scripts.html,/tutorials/best_practices/scenes_versus_scripts.html
 /getting_started/workflow/best_practices/what_are_godot_classes.html,/tutorials/best_practices/what_are_godot_classes.html
-/getting_started/workflow/export/android_custom_build.html,/tutorials/export/android_custom_build.html
+/getting_started/workflow/export/android_custom_build.html,/tutorials/export/android_gradle_build.html
 /getting_started/workflow/export/changing_application_icon_for_windows.html,/tutorials/export/changing_application_icon_for_windows.html
 /getting_started/workflow/export/exporting_for_android.html,/tutorials/export/exporting_for_android.html
 /getting_started/workflow/export/exporting_for_dedicated_servers.html,/tutorials/export/exporting_for_dedicated_servers.html

about/docs_changelog.rst

@@ -235,7 +235,7 @@ New pages since version 3.1
 Project workflow
 ^^^^^^^^^^^^^^^^
 
-- :ref:`doc_android_custom_build`
+- :ref:`doc_android_gradle_build`
 
 2D
 ^^

classes/class_editorexportplatformandroid.rst

@@ -21,7 +21,7 @@ Tutorials
 
 - :doc:`Exporting for Android <../tutorials/export/exporting_for_android>`
 
-- :doc:`Custom builds for Android <../tutorials/export/android_custom_build>`
+- :doc:`Gradle builds for Android <../tutorials/export/android_gradle_build>`
 
 - :doc:`Android plugins documentation index <../tutorials/platform/index>`
 

contributing/development/compiling/compiling_for_android.rst

@@ -94,8 +94,8 @@ root directory with the following arguments:
 
 ::
 
-    scons platform=android target=template_release arch=armv7
-    scons platform=android target=template_release arch=arm64v8
+    scons platform=android target=template_release arch=arm32
+    scons platform=android target=template_release arch=arm64
     cd platform/android/java
     # On Windows
     .\gradlew generateGodotTemplates
@@ -109,8 +109,8 @@ The resulting APK will be located at ``bin/android_release.apk``.
 
 ::
 
-    scons platform=android target=template_debug arch=armv7
-    scons platform=android target=template_debug arch=arm64v8
+    scons platform=android target=template_debug arch=arm32
+    scons platform=android target=template_debug arch=arm64
     cd platform/android/java
     # On Windows
     .\gradlew generateGodotTemplates
@@ -135,9 +135,9 @@ example, for the release template:
 
 ::
 
-    scons platform=android target=template_release arch=armv7
-    scons platform=android target=template_release arch=arm64v8
-    scons platform=android target=template_release arch=x86
+    scons platform=android target=template_release arch=arm32
+    scons platform=android target=template_release arch=arm64
+    scons platform=android target=template_release arch=x86_32
     scons platform=android target=template_release arch=x86_64
     cd platform/android/java
     # On Windows
@@ -160,9 +160,9 @@ You can use the following commands to remove the generated export templates:
 
     cd platform/android/java
     # On Windows
-    .\gradlew cleanGodotTemplates
+    .\gradlew clean
     # On Linux and macOS
-    ./gradlew cleanGodotTemplates
+    ./gradlew clean
 
 
 Using the export templates
@@ -213,9 +213,9 @@ root directory with the following arguments:
 
 ::
 
-   scons platform=android arch=armv7 production=yes target=editor
-   scons platform=android arch=arm64v8 production=yes target=editor
-   scons platform=android arch=x86 production=yes target=editor
+   scons platform=android arch=arm32 production=yes target=editor
+   scons platform=android arch=arm64 production=yes target=editor
+   scons platform=android arch=x86_32 production=yes target=editor
    scons platform=android arch=x86_64 production=yes target=editor
    cd platform/android/java
    # On Windows
@@ -224,7 +224,7 @@ root directory with the following arguments:
    ./gradlew generateGodotEditor
 
 
-The resulting APK will be located at ``bin/android_editor.apk``.
+The resulting APK will be located at ``bin/android_editor_builds/android_editor-release.apk``.
 
 Removing the Editor templates
 -----------------------------
@@ -235,9 +235,9 @@ You can use the following commands to remove the generated editor templates:
 
     cd platform/android/java
     # On Windows
-   .\gradlew cleanGodotEditor
+   .\gradlew clean
    # On Linux and macOS
-   ./gradlew cleanGodotEditor
+   ./gradlew clean
 
 Installing the Godot editor
 ---------------------------
@@ -247,7 +247,7 @@ Open up a Terminal/Command Prompt and run the following commands from the root d
 
 ::
 
-   adb install ./bin/android_editor.apk
+   adb install ./bin/android_editor_builds/android_editor-release.apk
 
 Troubleshooting
 ---------------

tutorials/export/android_custom_build.rst → tutorials/export/android_gradle_build.rst

@@ -1,10 +1,10 @@
-.. _doc_android_custom_build:
+.. _doc_android_gradle_build:
 
-Custom builds for Android
+Gradle builds for Android
 =========================
 
-Godot provides the option to use custom build Android templates. Instead of
-using the already pre-built template that ships with Godot, an actual Android
+Godot provides the option to build using the gradle buildsystem. Instead of
+using the already pre-built template that ships with Godot, an Android
 Java project gets installed into your project folder. Godot will then build it
 and use it as an export template every time you export the project.
 
@@ -13,45 +13,44 @@ There are some reasons why you may want to do this:
 * Modify the project before it's built.
 * Add external SDKs that build with your project.
 
-Configuring the custom build is a fairly straightforward process. But first
+Configuring the gradle build is a fairly straightforward process. But first
 you need to follow the steps in :ref:`exporting for android<doc_exporting_for_android>`
 up to **Setting it up in Godot**. After doing that, follow the steps below.
 
-Set up the custom build environment
+Set up the gradle build environment
 -----------------------------------
 
-Go to the Project menu, and install the *Custom Build* template:
+Go to the Project menu, and install the *Gradle Build* template:
 
-.. image:: img/custom_build_install_template.png
+.. image:: img/gradle_build_install_template.png
 
 Make sure export templates are downloaded. If not, this menu will help you
 download them.
 
 A Gradle-based Android project will be created under ``res://android/build``.
-Editing these files is not needed unless you want to :ref:`create
-your own add-ons<doc_android_plugin>`, or you really need to modify the project.
+Editing these files is not needed unless you really need to modify the project.
 
 
-Enabling the custom build and exporting
+Enabling the gradle build and exporting
 ---------------------------------------
 
 When setting up the Android project in the **Project > Export** dialog,
-**Custom Build** needs to be enabled:
+**Gradle Build** needs to be enabled:
 
-.. image:: img/custom_build_enable.png
+.. image:: img/gradle_build_enable.png
 
 From now on, attempting to export the project or one-click deploy will call the
 `Gradle <https://gradle.org/>`__ build system to generate fresh templates (this
 window will appear every time):
 
-.. image:: img/custom_build_gradle.png
+.. image:: img/gradle_build_gradle.png
 
 The templates built will be used automatically afterwards, so no further
 configuration is needed.
 
 .. note::
 
-    When using the custom Android build system, assets that are placed within a
+    When using the gradle Android build system, assets that are placed within a
     folder whose name begins with an underscore will not be included in the
     generated APK. This does not apply to assets whose *file* name begins with
     an underscore.

tutorials/export/index.rst

@@ -16,7 +16,7 @@ Export
    exporting_for_uwp
    exporting_for_ios
    exporting_for_android
-   android_custom_build
+   android_gradle_build
    exporting_for_web
    exporting_for_dedicated_servers
    one-click_deploy

tutorials/platform/android/android_in_app_purchases.rst

@@ -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)

tutorials/platform/android/android_library.rst

@@ -0,0 +1,51 @@
+.. _doc_android_library:
+
+Godot Android Library
+=====================
+
+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 buildsystem 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 will describe some of the use-cases and scenarios this flexible 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/4.1.0.stable>`_ along with `its documentation <https://javadoc.io/doc/org.godotengine/godot/latest/index.html>`_.
+
+As an Android library, it has been used to provide access to the Godot API on Android platforms for the following 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 themselves Android libraries with a dependency on the Godot Android library,
+which they use to access the Godot API and integrate into the engine's lifecycle.
+
+Their nature as Android libraries means they offer some of the same key features as the Godot Android library,
+notably the ability to integrate with the Gradle buildsystem, and the ability for the plugins themselves to be portable and embeddable.
+
+Their access to the Godot engine APIs and lifecycle grant them powerful capabilities
+such as GDExtension which allow them 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
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Due to its nature as an Android library, the Godot Engine can be easily 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 the provided APIs.
+These APIs can also be used to provide bidirectional communication between the host and the running Godot engine instance, allowing for greater control over the desired experience.
+
+Below, we walk-through how this is done using a sample app that exports and uses a Godot game as an embeddable Android view.