Added documentation about the new Custom Build system for Android

development/cpp/creating_android_modules.rst

@@ -1,360 +0,0 @@
-.. _doc_creating_android_modules:
-
-Creating Android modules
-========================
-
-Introduction
-------------
-
-Making video games portable is all fine and dandy, until mobile
-gaming monetization shows up.
-
-This area is complex, usually a mobile game that monetizes needs
-special connections to a server for things like:
-
--  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
-
-On iOS, you can write a C++ module and take advantage of the C++/ObjC
-intercommunication.
-
-On Android, interfacing with C++ through JNI (Java Native Interface) isn't as convenient.
-
-Maybe REST?
------------
-
-Most of these APIs allow communication via REST/JSON APIs. Godot has
-great support for HTTP, HTTPS and JSON, so consider this as an option
-that works on every platform. Only write the code once and you are set
-to go.
-
-Android module
---------------
-
-Writing an Android module is similar to :ref:`doc_custom_modules_in_c++`, but
-needs a few more steps.
-
-Make sure you are familiar with building your own :ref:`Android export templates <doc_compiling_for_android>`,
-as well as creating :ref:`doc_custom_modules_in_c++`.
-
-config.py
-~~~~~~~~~
-
-In the config.py for the module, some extra functions are provided for
-convenience. First, it's often wise to detect if Android is the target platform
-being built for and only enable building in this case:
-
-.. code:: python
-
-    def can_build(plat):
-        return plat=="android"
-
-If more than one platform can be built (typical if implementing the
-module also for iOS), check manually for Android in the configure
-functions for Android (or other platform-specific) code:
-
-.. code:: python
-
-    def can_build(plat):
-        return plat=="android" or plat=="iphone"
-
-    def configure(env):
-        if env['platform'] == 'android':
-            # android specific code
-
-Java singleton
---------------
-
-An Android module will usually have a singleton class that will load it,
-this class inherits from ``Godot.SingletonBase``. Resource identifiers for
-any additional resources you have provided for the module will be in the
-``com.godot.game.R`` class, so you'll likely want to import it.
-
-A singleton object template follows:
-
-.. code:: java
-
-    package org.godotengine.godot;
-
-    import android.app.Activity;
-    import android.content.Intent;
-    import com.godot.game.R;
-    import javax.microedition.khronos.opengles.GL10;
-
-    public class MySingleton extends Godot.SingletonBase {
-
-        protected Activity appActivity;
-        protected Context appContext;
-        private int instanceId = 0;
-
-        public int myFunction(String p_str) {
-            // a function to bind
-            return 1;
-        }
-
-        public void getInstanceId(int pInstanceId) {
-            // You will need to call this method from Godot and pass in the get_instance_id().
-            instanceId = pInstanceId;
-        }
-
-        static public Godot.SingletonBase initialize(Activity p_activity) {
-            return new MySingleton(p_activity);
-        }
-
-        public MySingleton(Activity p_activity) {
-            //register class name and functions to bind
-            registerClass("MySingleton", new String[]
-                {
-                    "myFunction",
-                    "getInstanceId"
-                });
-            this.appActivity = p_activity;
-            this.appContext = appActivity.getApplicationContext();
-            // you might want to try initializing your singleton here, but android
-            // threads are weird and this runs in another thread, so to interact with Godot you usually have to do
-            activity.runOnUiThread(new Runnable() {
-                    public void run() {
-                        //useful way to get config info from project.godot
-                        String key = GodotLib.getGlobal("plugin/api_key");
-                        //SDK.initializeHere();
-                    }
-            });
-
-        }
-
-        // forwarded callbacks you can reimplement, as SDKs often need them
-
-        protected void onMainActivityResult(int requestCode, int resultCode, Intent data) {}
-        protected void onMainRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {}
-
-        protected void onMainPause() {}
-        protected void onMainResume() {}
-        protected void onMainDestroy() {}
-
-        protected void onGLDrawFrame(GL10 gl) {}
-        protected void onGLSurfaceChanged(GL10 gl, int width, int height) {} // singletons will always miss first onGLSurfaceChanged call
-
-    }
-
-Calling back to Godot from Java is a little more difficult. The instance
-ID of the script must be known first, this is obtained by calling
-``get_instance_ID()`` on the script. This returns an integer that can be
-passed to Java.
-
-From Java, use the ``calldeferred`` function to communicate back with Godot.
-Java will most likely run in a separate thread, so calls are deferred:
-
-.. code:: java
-
-    GodotLib.calldeferred(<instanceid>, "<function>", new Object[]{param1,param2,etc});
-
-Add this singleton to the build of the project by adding the following
-to config.py:
-
-.. code:: python
-
-    def can_build(plat):
-        return plat=="android" or plat=="iphone"
-
-    def configure(env):
-        if env['platform'] == 'android':
-            # will copy this to the java folder
-            env.android_add_java_dir("Directory that contain MySingleton.java")
-
-
-
-AndroidManifest
----------------
-
-Some SDKs need custom values in AndroidManifest.xml. Permissions can be
-edited from the Godot exporter so there is no need to add those, but
-maybe other functionalities are needed.
-
-Create the custom chunk of android manifest and put it inside the
-module, add it like this:
-
-.. code:: python
-
-    def can_build(plat):
-        return plat=="android" or plat=="iphone"
-
-    def configure(env):
-        if env['platform'] == 'android':
-            # will copy this to the java folder
-            env.android_add_java_dir("Directory that contains MySingleton.java")
-            env.android_add_to_manifest("AndroidManifestChunk.xml")
-
-
-
-Resources
----------
-
-In order to provide additional resources with your module you have to
-add something like this:
-
-.. code:: python
-
-    def configure(env):
-        if env['platform'] == 'android':
-            # [...]
-            env.android_add_res_dir("Directory that contains resource subdirectories (values, drawable, etc.)")
-
-Now you can refer to those resources by their id (``R.string.my_string``, and the like)
-by importing the ``com.godot.game.R`` class in your Java code.
-
-Assets
-------
-
-Similarly, you can add any type of raw asset files to your app's asset directory like this:
-
-.. code:: python
-
-    def configure(env):
-        if env['platform'] == 'android':
-            # [...]
-            env.android_add_asset_dir("Directory that contains asset files for your app")
-
-Assets don't have resource ids, but can be read with their file name as streams of bytes with the help
-of the Android AssetManager class.
-
-SDK library
------------
-
-So, finally it's time to add the SDK library. The library can come in
-two flavors, a JAR file or an Android project for ant. JAR is the
-easiest to integrate, put it in the module directory and add it:
-
-.. code:: python
-
-    def can_build(plat):
-        return plat=="android" or plat=="iphone"
-
-    def configure(env):
-        if env['platform'] == 'android':
-            # will copy this to the java folder
-            env.android_add_java_dir("Directory that contains MySingleton.java")
-            env.android_add_to_manifest("AndroidManifestChunk.xml")
-            env.android_add_dependency("compile files('something_local.jar')") # if you have a jar, the path is relative to platform/android/java/gradlew, so it will start with ../../../modules/module_name/
-            env.android_add_maven_repository("maven url") #add a maven url
-            env.android_add_dependency("compile 'com.google.android.gms:play-services-ads:8'") #get dependency from maven repository
-
-
-SDK project
------------
-
-When this is an Android project, things usually get more complex. Copy
-the project folder inside the module directory and configure it:
-
-::
-
-    c:\godot\modules\mymodule\sdk-1.2> android -p . -t 15
-
-As of this writing, Godot uses minsdk 18 and target sdk 27. If this ever
-changes, it should be reflected in the manifest template:
-`AndroidManifest.xml.template <https://github.com/godotengine/godot/blob/master/platform/android/AndroidManifest.xml.template>`__
-
-Then, add the module folder to the project:
-
-.. code:: python
-
-    def can_build(plat):
-        return plat=="android" or plat=="iphone"
-
-    def configure(env):
-        if env['platform'] == 'android':
-            # will copy this to the java folder
-            env.android_module_file("MySingleton.java")
-            env.android_module_manifest("AndroidManifestChunk.xml")
-            env.android_module_source("sdk-1.2","")
-
-
-Building
---------
-
-As you probably modify the contents of the module, and modify your .java
-inside the module, you need the module to be built with the rest of
-Godot, so compile android normally.
-
-::
-
-    c:\godot> scons p=android
-
-This will cause your module to be included, the .jar will be copied to
-the java folder, the .java will be copied to the sources folder, etc.
-Each time you modify the .java, scons must be called.
-
-Afterwards, continue the steps for compiling android  :ref:`doc_compiling_for_android`.
-
-Using the module
-~~~~~~~~~~~~~~~~
-
-To use the module from GDScript, first enable the singleton by adding
-the following line to project.godot:
-
-::
-
-    [android]
-
-    modules="org/godotengine/godot/MySingleton"
-
-More than one singleton module can be enabled by separating with commas:
-
-::
-
-    [android]
-
-    modules="org/godotengine/godot/MySingleton,org/godotengine/godot/MyOtherSingleton"
-
-Then request the singleton Java object from Globals like this:
-
-::
-
-    # in any file
-
-    var singleton = null
-
-    func _init():
-        singleton = Globals.get_singleton("MySingleton")
-        print(singleton.myFunction("Hello"))
-
-Troubleshooting
----------------
-
-Godot crashes upon load
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Check ``adb logcat`` for possible problems, then:
-
--  Make sure libgodot_android.so is in the ``libs/armeabi`` folder
--  Check that the methods used in the Java singleton only use simple
-   Java datatypes, more complex ones are not supported.
-
-Future
-------
-
-Godot has an experimental Java API Wrapper that allows to use the
-entire Java API from GDScript.
-
-It's simple to use and it's used like this:
-
-::
-
-    class = JavaClassWrapper.wrap(<javaclass as text>)
-
-This is most likely not functional yet, if you want to test it and help
-us make it work, contact us through the `developer mailing
-list <https://groups.google.com/forum/#!forum/godot-engine>`__.

development/cpp/index.rst

@@ -16,4 +16,3 @@ Engine development
    custom_resource_format_loaders
    custom_audiostreams
    custom_godot_servers
-   creating_android_modules

getting_started/workflow/export/android_custom_build.rst

@@ -0,0 +1,206 @@
+.. _doc_android_custom_build:
+
+Custom 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 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.
+
+There are some reasons why you may want to do this:
+
+* Modify the project before it's build
+* Add external SDKs that build with your project
+
+Configuring custom build is a more or less straightforward process, but it may take a while to get used to how the Android SDK works.
+
+Instructions will try to be provided as detailed as possible to do this process.
+
+Set up the Custom Build environment
+------------------------------------
+
+Go to the Project menu, and install the *Custom Build* template:
+
+.. image:: img/custom_build_install_template.png
+
+Make sure export templates are downloaded. If not, this menu will aid you to do it.
+
+This will create an Gradle-based Android project in *"res://android/build"*, and place a .gdignore file in *"res://android"* so Godot filesystem ignores this folder. Editing these files is not needed unless you want to create your own add-ons, or you really need to modify the project.
+
+Install the Android SDK (Command Line Version)
+----------------------------------------------
+
+These are the steps for installing the Android SDK using command line. The advantage of this approach is the simplicity and small download/install size. It can be a bit more challenging, though. The Android Studio approach is easier but it requires downloading and installing Android Studio (which is more than 1gb).
+
+Install Java
+^^^^^^^^^^^^^
+
+Android SDK does not come with Java, so it needs to be installed manually. Instal Java SDK (**not** runtime or JRE). OpenSDK 8 is recommended, otherwise Oracle's Java SDK for version 8 will work. Later versions may not work for Android development.
+
+Download the command line tools
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Go to Google's website for downloading the Android SDK. A search will take you to the *Android Studio* download page.
+You don't want it, so don't download (if you do want it, read further down for instructions for doing the same using Android Studio).
+
+Look in that page for the *Command Line Tools*. Currently, they are listed under *Download Options*. Scroll down a bit until you see them.
+
+.. image:: img/custom_build_command_line.png
+
+Download the zip file for your platform, inside there will be a single *tools* folder:
+
+.. image:: img/custom_build_zip.png
+
+This may appear a little confusing, but be sure to follow these instructions carefully:
+
+* Create a new folder anywhere you want named *android-sdk* (it **must** be an empty directory). On Windows, *"C:\users\<yourusername>\Documents\android-sdk"* is often good.
+* Unzip the *sdk zip file* you just downloaded there. The only thing in the directory you created in the previous step should be the *tools* folder with it's contents inside, like this:
+
+::
+
+   android-sdk/
+   android-sdk/tools/
+   android-sdk/tools/allthefiles
+
+
+Accepting the Licenses
+^^^^^^^^^^^^^^^^^^^^^^
+
+Everything would be more or less rosy up to here, but in order to even do anything, Google requires you to accept its licenses.
+
+To do this, the *sdkmanager* must be executed from command line with a special argument. Navigate to the *tools/bin* directory inside the sdk folder (instructions provided for Windows users, as Unix users are expected to understand how command line navigation works):
+
+.. image:: img/custom_build_bin_folder.png
+
+Then open a command line window:
+
+.. image:: img/custom_build_open_shell.png
+
+In there, manually run sdkmanager with the "--licenses" argument:
+
+.. image:: img/custom_build_sdkmanager.png
+
+This will ask you to accept several licenses, just write *"y"* and press *enter* on every of them until it's done.
+
+Afterwards, install the platform tools (this is needed to install *adb*):
+
+.. image:: img/custom_build_platform_tools.png
+
+
+Generating the Keystore
+^^^^^^^^^^^^^^^^^^^^^^
+
+Once *platform tools* are installed, the last step is to generate a debug keystore (this is needed to build). Go up two folders by
+writing:
+
+::
+
+    cd ..\..
+
+(or open a new shell on the *android-sdk* folder).
+
+And you need to input the following line (on Unixes this should work out of the box, for Windows there are further instructions below):
+
+::
+
+    keytool -keyalg RSA -genkeypair -alias androiddebugkey -keypass android -keystore debug.keystore -storepass android -dname "CN=Android Debug,O=Android,C=US" -validity 9999
+
+On Windows, the full path to Java should be provided (and & needs to be added at the beginning on the line if you use PowerShell, it's not needed for regular console). 
+
+To make it clearer, here is an capture of a line that works on PowerShell (by adding & and the full Java Path to keytool.exe). Again, keep in mind that you need Java installed:
+
+. image:: img/custom_build_command_line.png
+
+
+Setting up Godot
+^^^^^^^^^^^^^^^^
+
+Go to the *Editor Settings* and set up a few fields in *Export -> Android*. Make sure they look like the following:
+
+.. image:: img/custom_build_editor_settings.png
+
+As it can be seen, most paths are inside either *android-sdk* you originally created, or inside the Java install. For Unix users, *jarsigner* is often in "/usr/bin".
+
+With this, you should be all set.
+
+
+Install the Android SDK (Android Studio)
+----------------------------------------------
+
+If you just finished installing the SDK via command line tools, feel free to skip this section entirely. The Android Studio path is easier, but it takes up more disk space. It's also useful if you plan to develop Godot for Android (modify the Java source code) or if you plan to develop Add-Ons.
+
+Download and Install Android Studio
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Download the latest version of Android Studio. When installing, pay attention to where the *android-sdk* directory is created.
+
+.. image:: img/custom_build_editor_settings.png
+
+.. note:: This is funny, the path it proposes by default contains whitespace (and complains about it). It must be changed.
+
+In any case, it's better to select a different path inside your user folders. The recommended one is usually:
+
+::
+
+   C:\Users\<yourusername>\Documents\android-sdk
+
+Replace *yourusername* by your actual user name. Once it's correct, select from the list above in the same screen:
+
+* Android SDK
+* Android SDK Platform
+
+The rest are not needed, because the build system will fetch them itself. After selecting them, go on with the installation.
+
+
+Generating the Keystore
+^^^^^^^^^^^^^^^^^^^^^^
+
+You thought that by going the Android Studio way you could escape the Keystore generation, but no. It's back to haunt you.
+
+Go to the folder where you installed android-sdk in the previous step, use File Explorer and open a command line tool there:
+
+.. image:: img/custom_build_open_shell.png
+
+The actual command line to type is the following. On Unixes it should work out of the box, but on Windows it needs additional details (keep reading afterwards).
+
+::
+
+    keytool -keyalg RSA -genkeypair -alias androiddebugkey -keypass android -keystore debug.keystore -storepass android -dname "CN=Android Debug,O=Android,C=US" -validity 9999
+
+On Windows, the full path to Java should be provided (and & needs to be added at the beginning on the line if you use PowerShell, it's not needed for regular commandline). Don't worry, at least by using Android Studio on Windows, Java comes bundled with it.
+
+To make it clearer, here is a screen capture of a line that works on PowerShell (by adding & and the full Java Path to keytool.exe, remove & if you use regular console). It uses a path to the Java version that comes with Android Studio:
+
+. image:: img/custom_build_command_line2.png
+
+Setting up Godot
+^^^^^^^^^^^^^^^^
+
+Go to the *Editor Settings* and set up a few fields in *Export -> Android*. Make sure they look like the following:
+
+.. image:: img/custom_build_editor_settings2.png
+
+As it can be seen, most paths are inside either *android-sdk* you originally created, or inside the Java install. For Unix users, *jarsigner* is often in "/usr/bin".
+
+With this, you should be all set.
+
+
+Enabling Custom Build and Exporting
+------------------------------------
+
+When setting up the Android project in the *Project -> Export* dialog, *custom build* needs to be enabled:
+
+.. image:: img/custom_build_enable.png
+
+From now on, attempting to export the project or one-click deploy will call the *Gradle* build system to generate fresh templates (this window will appear every time):
+
+.. image:: img/custom_build_gradle.png
+
+The templates built will be used automatically afterwards, so no further configuration is needed.
+
+
+
+
+
+
+

getting_started/workflow/export/index.rst

@@ -15,4 +15,5 @@ Export
    exporting_for_android
    exporting_for_web
    one-click_deploy
+   android_custom_build
    changing_application_icon_for_windows

tutorials/plugins/android/android_plugin.rst

@@ -0,0 +1,280 @@
+.. _doc_android_plugin:
+
+Creating Android Plugins
+========================
+
+Introduction
+------------
+
+Making video games portable is all fine and dandy, until mobile
+gaming monetization shows up.
+
+This area is complex, usually a mobile game that monetizes needs
+special connections to a server for things like:
+
+-  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
+
+On iOS, you can write a C++ module and take advantage of the C++/ObjC
+intercommunication. Even using GDNative is possible to make it a plug-in.
+
+On Android, interfacing with C++ through JNI (Java Native Interface) isn't as flexible, so writing plugins
+is considerably more work.
+
+It is also possible that you just want to do modifications to the Android export template, and by using a plugin your project
+can remain compatible with newer Godot versions (as the android source template will get updated on each release).
+
+Maybe REST
+-----------
+
+Most of these APIs allow communication via REST/JSON APIs. If the API is relatively simple and does not require
+complex authenthication, this may be a better idea than writing a specific Android plugin.
+
+Godot has great support for HTTP, HTTPS and JSON, so an API implemented this way
+will work on every platform, too. 
+
+Of course, in most of the cases, it's easier to just write an Android plugins, so keep reading.
+
+Android plugin
+--------------
+
+Writing an Android plugin is now possible begining Godot 3.2. It's also pretty easy!
+
+Before anything, make sure you understand how to set up a :ref:`custom build environment<doc_android_custom_build>` for Android.
+
+You plugin needs to be a folder other than *"build/"* inside the *"res://android"* directory (which was created by following the link above). Any name is fine, so name it according to the SDK you will implement (or just your plugin name).
+
+Once created, there are certain rules to follow, but they are simple.
+
+Android Directories
+^^^^^^^^^^^^^^^^^^^
+
+Inside your plugin folder, you can use the standard folders as if they were from an Android Gradle project. Examples of this are:
+
+::
+
+   src/ - For Java source code, same as in your Android project
+   res/ - For resources
+   aidl/ - For interfaces
+   assets/ - For assets that will be included as-is on export
+   libs/debug - For debug JNI libraries
+   libs/release - For release JNI libraries
+
+Gradle will treat them as part of the project automatically when building, same as the default project files.
+
+"Chunk" files
+^^^^^^^^^^^^^
+
+it is possible to modify *"AndroidManifest.xml"* and *build.gradle* in *"res://android/build"* directly and Godot will keep your
+changes when building. The problem, however, is that if you update Godot, you will also need to update the *build/* folder and your
+changes will be lost.
+
+To overcome this, the Godot Android Plugin system lets you create *chunk* files, where you can specify little bits that can be
+inserted in both *"AndroidManifest.xml"* and *build.gradle*. They are inserted every time Godot builds the project for export or deploy.
+
+AndroidManifest.conf
+~~~~~~~~~~~~~~~~~~~~
+
+This file allows to insert bits of chunk into *AndroidManifest.xml*, the following are supported tags and are entirely optional:
+
+::
+
+   [user_permissions]
+
+Any bit of text below this tag is inserted inside the <manifest> tag of the file. This is often used for permission tags.
+
+::
+
+   [application]
+
+Any bit of text below this tag inside the <application> tag of the file. Many SDKs require this.
+
+::
+
+   [application_attribs]
+
+These are attributes you can add at the end of the <application> tag. Some SDKs require this.
+
+gradle.conf
+~~~~~~~~~~~
+
+This file allows to insert bits of chunk into *build.gradle*, the following are supported and are entirely optional:
+
+::
+
+   [buildscript_repositories]
+
+
+Any bit of text below this tag is inserted inside the buildscript.repositories section of the build file.
+
+
+::
+
+   [buildscript_dependencies]
+
+
+Any bit of text below this tag is inserted inside the buildscript.dependencies section of the build file.
+
+::
+
+   [allprojects_repositories]
+
+
+Any bit of text below this tag is inserted inside the allprojects.repositories section of the build file.
+
+::
+
+   [dependencies]
+
+
+Any bit of text below this tag is inserted inside the dependencies section of the build file.
+
+
+::
+
+   [android_defaultconfig]
+
+
+Any bit of text below this tag is inserted inside the android.defaultconfig section of the build file.
+
+::
+
+   [global]
+
+
+Any bit of text below this tag is inserted inside the global scope of the build file.
+
+Java singleton
+--------------
+
+An Android plugin will usually have a singleton class that will load it,
+this class inherits from ``Godot.SingletonBase``. Resource identifiers for
+any additional resources you have provided for the module will be in the
+``com.godot.game.R`` class, so you'll likely want to import it.
+
+A singleton object template follows:
+
+.. code:: java
+
+    package org.godotengine.godot;
+
+    import android.app.Activity;
+    import android.content.Intent;
+    import com.godot.game.R;
+    import javax.microedition.khronos.opengles.GL10;
+
+    public class MySingleton extends Godot.SingletonBase {
+
+        protected Activity appActivity;
+        protected Context appContext;
+        private int instanceId = 0;
+
+        public int myFunction(String p_str) {
+            // a function to bind
+            return 1;
+        }
+
+        public void getInstanceId(int pInstanceId) {
+            // You will need to call this method from Godot and pass in the get_instance_id().
+            instanceId = pInstanceId;
+        }
+
+        static public Godot.SingletonBase initialize(Activity p_activity) {
+            return new MySingleton(p_activity);
+        }
+
+        public MySingleton(Activity p_activity) {
+            //register class name and functions to bind
+            registerClass("MySingleton", new String[]
+                {
+                    "myFunction",
+                    "getInstanceId"
+                });
+            this.appActivity = p_activity;
+            this.appContext = appActivity.getApplicationContext();
+            // you might want to try initializing your singleton here, but android
+            // threads are weird and this runs in another thread, so to interact with Godot you usually have to do
+            activity.runOnUiThread(new Runnable() {
+                    public void run() {
+                        //useful way to get config info from project.godot
+                        String key = GodotLib.getGlobal("plugin/api_key");
+                        //SDK.initializeHere();
+                    }
+            });
+
+        }
+
+        // forwarded callbacks you can reimplement, as SDKs often need them
+
+        protected void onMainActivityResult(int requestCode, int resultCode, Intent data) {}
+        protected void onMainRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {}
+
+        protected void onMainPause() {}
+        protected void onMainResume() {}
+        protected void onMainDestroy() {}
+
+        protected void onGLDrawFrame(GL10 gl) {}
+        protected void onGLSurfaceChanged(GL10 gl, int width, int height) {} // singletons will always miss first onGLSurfaceChanged call
+
+    }
+
+Calling back to Godot
+~~~~~~~~~~~~~~~~~~~~~
+
+Calling back to Godot from Java is a little more difficult. The instance
+ID of the script must be known first, this is obtained by calling
+``get_instance_ID()`` on the script. This returns an integer that can be
+passed to Java.
+
+From Java, use the ``calldeferred`` function to communicate back with Godot.
+Java will most likely run in a separate thread, so calls are deferred:
+
+.. code:: java
+
+    GodotLib.calldeferred(<instanceid>, "<function>", new Object[]{param1,param2,etc});
+
+
+Godot will detect this singleton and initialize it at the proper time.
+
+
+Troubleshooting
+---------------
+
+Godot crashes upon load
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Check ``adb logcat`` for possible problems, then:
+
+-  Make sure libgodot_android.so is in the ``libs/armeabi`` folder
+-  Check that the methods used in the Java singleton only use simple
+   Java datatypes, more complex ones are not supported.
+
+Future
+------
+
+Godot has an experimental Java API Wrapper that allows to use the
+entire Java API from GDScript.
+
+It's simple to use and it's used like this:
+
+::
+
+    class = JavaClassWrapper.wrap(<javaclass as text>)
+
+This is most likely not functional yet, if you want to test it and help
+us make it work, contact us on irc.freenode.org:#godotengine-devel.
+

tutorials/plugins/android/index.rst

@@ -0,0 +1,8 @@
+Android Plugins
+================
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-tutorials-plugins-android
+
+   android_plugin

tutorials/threads/using_multiple_threads.rst

@@ -57,6 +57,8 @@ the same data directly from different threads. You may run into synchronization
 data is not always updated between CPU cores when modified.
 Always use a :ref:`Mutex<class_Mutex>` when accessing a piece of data from different threads.
 
+When calling :ref:`Mutex.lock()<class_Mutex_method_lock>`, a thread ensures that all other threads will be blocked (put on suspended state) if they try to *lock* the same mutex. When the mutex us unlocked by calling :ref:`Mutex.unlock()<class_Mutex_method_unlock>`, the other threads will be allowed to proceed with the lock (but only one at a time).  
+
 Here is an example of using a Mutex:
 
 .. tabs::