Creating Android modules¶
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 stuff such as:
- 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
Oh yeah, developing for mobile is a lot of work. On iOS, you can just write a C++ module and take advantage of the C++/ObjC intercommunication, so this is rather easy.
For C++ developers Java is a pain, the build system is severely bloated and interfacing it with C++ through JNI (Java Native Interface) is more pain that you don’t want even for your worst enemy.
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 in every platform. Only write the code once and you are set to go.
Popular engines that have half the share of apps published on mobile get special plugins written just for them. Godot does not have that luxury yet. So, if you write a REST implementation of a SDK for Godot, please share it with the community.
Android module¶
Writing an Android module is similar to Custom modules in C++ , but needs a few more steps.
Make sure you are familiar with building your own Android export templates , as well as creating 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 being built and only enable building in this case:
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:
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 . A singleton object template follows:
// package com.android.godot; // for 1.1 package org.godotengine.godot; // for 2.0 public class MySingleton extends Godot.SingletonBase public int myFunction(String p_str) // a function to bind > 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">); // you might want to try initializing your singleton here, but android // threads are weird and this runs in another thread, so you usually have to do activity.runOnUiThread(new Runnable() public void run() //useful way to get config info from engine.cfg 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 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:
GodotLib.calldeferred(instanceid>, "", new Object[]param1,param2,etc>);
Add this singleton to the build of the project by adding the following to config.py:
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_file("MySingleton2.java") call again for more files
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 MySingelton.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:
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")
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 MySingelton.java") env.android_add_to_manifest("AndroidManifestChunk.xml")
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, just put it in the module directory and add it:
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_library("MyLibrary-3.1.jar")
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 MySingelton.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 10 and target sdk 15. If this ever changes, it should be reflected in the manifest template: AndroidManifest.xml.template
Then, add the module folder to the project:
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.
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, just continue the steps for compiling android Compiling for Android .
Using the module¶
To use the module from GDScript, first enable the singleton by adding the following line to engine.cfg (Godot Engine 2.0 and greater):
[android] modules="org/godotengine/godot/MySingleton"
[android] modules="com/android/godot/MySingleton"
More than one singleton module can be enabled by separating with commas:
[android] modules="com/android/godot/MySingleton,com/android/godot/MyOtherSingleton"
Then just 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¶
(This section is a work in progress, report your problems here!)
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.
© Copyright 2014-2016, Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0). Revision 577559cf .
Versions latest Downloads pdf htmlzip epub On Read the Docs Project Home Builds Free document hosting provided by Read the Docs.
Requirements
Before starting a project make sure you read the Exporting documentation! Depending on your chosen platform (like native images with GraalVM or Android) there are important details to consider (like third party dependencies and host systems to compile your game on).
Failure to do so or understanding what is needed can lead to big problems once you’re at the stage of exporting and shipping your project.
Also make sure to regularily test your exports on each platform. It’s best to even test the exports on each platform before even writing anything else than the first test class
Java
To use this module at least JDK 11 is needed, note you will need the JDK not just the JRE, and the environment variable JAVA_HOME to be present before being able to run the custom godot editor.
Mac & Linux
You can install Java via SDKMAN!. Once you installed it, you can run sdk install java 11.0.11.hs-adpt to install the LTS version of Java from AdoptOpenJDK. If you want to pick a different version, you can run sdk list java .
Windows
You can install Java via Chocolatey. For example, to install AdoptOpenJDK you can run choco install adoptopenjdk11 .
IDE
There is currently no plan to support the built-in Godot editor, using IntelliJ IDEA is strongly recommended (the community edition is free). Editors such as VSCode can be used, however, we only provide first class support for IntelliJ IDEA. You can install it via JetBrains Toolbox app.
Intellij IDEA plugin
We also recommend installing our IntelliJ IDEA plugin as it provides you with a lot of useful checks and helpers to detect errors during development.
Godot Editor
You need our custom engine build from the latest GitHub release to be able to use this project. If you need other modules you can also build it yourself.
Exporting
You need our custom export templates for your exported games to work with the jvm. Have a look at the Exporting documentation.