Add "library" and "GameActivity" support for Android

[manake]

Describe the project you are working on

A native Android app that wants to have:

1. A single Activity with Android Studio UI elements and Godot 3D elements at the same time (on one screen).
2. Modern GameActivity.

Describe the problem or limitation you are having in your project

1. Godot doesn't offer export as a library (it's an application), like Unity does, which makes integrating into native Android applications either (1) impossible at all (I'm not sure if the Gradle template can be manually configured to make it a library) or (2) time-consuming and complicated.
2. The Android documentation recommends using GameActivity for C++ 3D code: https://developer.android.com/games/agdk/game-activity

Describe the feature / enhancement and how it helps to overcome the problem or limitation

1. Make Android Gradle project a library that can be fully independent and easily insertable into native Android applications.
2. Make GameActivity hold C++ of Godot, with an ability to extend it with overlayed custom UI elements.
3. Add documentation that explains how C++ gets inserted into GameActivity, so that native app integrators can understand this. Make a picture in the documentation that explains this like they have here: https://developer.android.com/games/agdk/game-activity

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

It's best to see how Unity did it and do it the same way because their implementation worked for me out of the box the way I wanted:
- https://forum.unity.com/threads/introducing-gameactivity-for-android-in-2023-1.1409418/
- https://github.com/Unity-Technologies/uaal-example

If this enhancement will not be used often, can it be worked around with a few lines of script?

It can't be worked around.

Unity said in their post that they had to make C++ modifications in the engine to enable GameActivity support.

Is there a reason why this should be core and not an add-on in the asset library?

1. This use case of integrating 3D elements into native apps should have a steady interest for years to come.
2. Unity has it as a core feature here: https://unity.com/features/unity-as-a-library
3. Delivering (1) the most basic Gradle project with Godot as a library and with GameActivity is like the entry point for generating (2) more advanced Gradle projects and finally (3) APK/AAB.

Point 1 from this chain is kind of missing in Godot currently and only 2 and 3 are present: (1) Basic library project --> (2) More advanced Gradle project --> (3) APK/AAB

[Calinou]

Godot doesn't offer export as a library (it's an application), like Unity does, which makes integrating into native Android applications either (1) impossible at all (I'm not sure if the Gradle template can be manually configured to make it a library) or (2) time-consuming and complicated.

See #1473. This is already supported on Android, but it was unfortunately never documented and nobody is currently available to write this documentation.

[manake]

I started investigating it. I'm busy with other tasks though, so it would be better if someone else picked it up and finished.

If [File -> Export... -> Android] doesn't have "export as a library" option then it most likely isn't fully implemented.

Here's the beginning of a new documentation page that could replace all existing documentation pages on the subject of exporting for Android.

(Having Godot only export library and have no capability of building APK/AAB is what I think is the ideal approach, since introduction of GameActivity 1-2 years ago it makes less and less sense for Godot to build APK/AAB due to the fact that GameActivity passes Java events to C++ libraries now etc. so the integration process has changed since historical NativeActivity times.)

Title: Exporting for Android

Description: Learn how to include Godot in your Android project and how to have a releasable AAB/APK file.

1. Learn how to include Godot in your Android project

1. Install the newest version of Android Studio.

   • This tutorial will be in Kotlin only because Java doesn't support features like Compose.

2. Create your Android application.

   • You should create a fully working application with at least 1 Java or Kotlin file (your MainActivity.kt class) and you should have fully configured build.gradle and manifest.xml files.
   • You should configure your app icon, specify desired permissions (like INTERNET access), install any necessary libraries like authentication, multiplayer, ads, setup your debug and release keystores etc. You should generally code as much as you can in Java/Kotlin and ideally Godot should only be your 2D/3D rendering part that will be displayed as a Android View (Surface).
   • Upload your app to your Android device. It should be fully working at this point.

3. Go to your entry point class (we assume /java/com/example/yourproject/MainActivity.kt) and modify it to class MainActivity : GameActivity() (import the necessary dependencies in build.gradle and read the documentation about what GameActivity is before you do it).

4. Add companion object with init { System.loadLibrary('yourproject') }.

5. Go to Godot to [File -> Export... -> Android] and select "Library" in export type. Hit "Export" and export your project to some location like D:/GodotProjects/yourproject.

   • This is a library for use in Android Studio. It must be included in an existing Android application and it can't be used to build an APK/AAB by itself.

6. [STEP 6 AND FURTHER STEPS ARE NOT FINISHED. BASICALLY THERE ARE 2 WAYS TO PROCEED HERE:]

   • Copy /cpp/ folder from your D:/GodotProjects/yourproject and paste it into your Android app into the same place and edit manifest.xml to define "yourproject" C++ library as available and create a rendering Surface in MainActivity and load "yourproject" (the C++ of Godot).
   • Or simply include the Godot's output as a library in your project. You then need to edit both your Android project and D:/GodotProjects/yourproject Android project separately. You can also have for example 10 separate Godot projects included in 1 Android application this way.

2. Building APK/AAB

You can build your APK/AAB directly from [File -> Export... -> Android] but this is no longer recommended because you won't be able to easily include any Java libraries in your project. Instead, it's better to include Android library of your Godot project in your own Android app and build APK/AAB with Android Studio.

[mahdisml]

It can also fix some problems :
godotengine/godot#66318

[Alex2782]

maybe fixed (TouchScreenButton): godotengine/godot#83301 (comment)

I think a port will be very high effort, more than 5000 lines of code.

A few days ago I tried agdktunnel demo -> android_input_buffer
Docs: add-touch-support

In Godot, the TouchEvent are intercepted individually, processed and checked for "gestures" first, then collected in the Vector<TouchPos> touch

[m4gr3d]

Documentation available in https://docs.godotengine.org/en/stable/tutorials/platform/android/android_library.html