Benutzerdefinierte Builds für 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 built.
  • Füge externe SDKs die mit Ihrem Projekt verarbeitet werden.

Configuring the 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 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:

../../../_images/custom_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 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 more challenging though. The Android Studio approach is easier, but it requires downloading and installing Android Studio (which may require more than 1 GB of storage).

Installation eines JDK

The Android SDK doesn't come with Java, so it needs to be installed manually. You need to install a Java SDK (not just the runtime or JRE). OpenJDK 8 is required, newer versions won't work.

On Windows, make sure that you enable "Set JAVA_HOME variable" in the Custom Setup view of the installer. You have to restart Godot after this, otherwise Godot can't find the JAVA_HOME variable.

Hilfsmittel für die Kommandozeile herunterladen

Go to the Android Studio download page. To save disk space, you don't want the full IDE, so don't download it.

Bemerkung

If you do want Android Studio, read further down for instructions for doing the same using Android Studio.

Look on that page for the Command line tools only section. Currently, they are listed under Download Options. Scroll down a bit until you see them and download the ZIP file for your platform.

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, the following path is usually good enough:

C:\users\<yourusername>\android-sdk

Create an empty folder named cmdline-tools inside of the android-sdk folder. Then unzip the Android SDK ZIP file into the android-sdk/cmdline-tools folder.

Bemerkung

If you're on Windows, you must not extract the ZIP archive with the default Windows extractor (e.g. Windows Explorer). You have to use another tool like 7zip, WinRAR or the Powershell Expand-Archive command. If you extract the archive with the default Windows extractor, the files are not extracted correctly and you will run into errors later on!

The cmdline-tools folder should now contain the unzipped folder called tools. Finally, rename the tools folder to latest.

Your final directory structure should look like this :

android-sdk/
android-sdk/cmdline-tools/
android-sdk/cmdline-tools/latest
android-sdk/cmdline-tools/latest/allTheOtherFiles

We need to setup the directory structure this way for the sdkmanager (inside the bin folder) to work.

Die Lizenz akzeptieren

To be able to use the Android SDK tools, Google requires you to accept its licenses.

To do this, the sdkmanager must be executed from the command line with a special argument. Navigate to the tools/bin directory inside the SDK folder (instructions provided for Windows users, as Linux and macOS users are expected to understand how command line navigation works):

../../../_images/custom_build_bin_folder.png

Then open a command line window:

../../../_images/custom_build_open_shell.png

falls vorhanden, starten Sie sdkmanager --licenses:

../../../_images/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 required to install adb):

../../../_images/custom_build_platform_tools.png

If you get an error saying Warning: Could not create settings, try ./sdkmanager --sdk_root=../../ --licenses or ./sdkmanager --sdk_root=../../ platform-tools. These must be executed inside the /tools/bin/ folder because the path for --sdk_root is relative.

Einen Keystore (Schlüsselwert) generieren

Once the 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 in the android-sdk folder).

And you need to input the following line (This should work out of the box. However, if you haven't set the JAVA_HOME variable on 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, if you did not install the JAVA_HOME variable, the full path to Java should be provided. You need to add & at the beginning of the line if you use PowerShell; it's not needed for the regular cmd.exe console.

To make it clearer, here is an capture of a line that works on PowerShell (by adding & and the full Java path before keytool.exe). Again, keep in mind that you need Java installed:

../../../_images/custom_build_command_line.png

(right-click and open the image in a new tab if this appears too small)

Godot einrichten

Go to the Editor Settings and set up a few fields in Export > Android. Make sure they look like the following:

../../../_images/custom_build_editor_settings.png

(right-click and open the image in a new tab if this appears too small)

As it can be seen, most paths are inside either the android-sdk folder you originally created, or inside the Java install. For Linux and macOS users, jarsigner is often located in /usr/bin.

With this, you should be all set.

Install the Android SDK (Android Studio)

If you just finished installing the SDK via the 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.

Laden Sie Android Studio herunter und installieren es

Download the latest version of Android Studio. When installing, pay attention to where the android-sdk directory is created.

../../../_images/custom_build_install_android_studio1.png

Bemerkung

Das ist lustig. Der Pfad, den es standardmäßig vorschlägt enthält Leerzeichen (und beschwert sich darüber). Er muss geändert werden.

In jedem Fall ist es besser, einen anderen Pfad innerhalb des Benutzerverzeichnisses zu wählen. Der empfohlene ist in der Regel:

C:\Users\<yourusername>\Documents\android-sdk

Ersetzen Sie yourusername durch Ihren tatsächlichen Benutzernamen. Sobald er korrekt ist, wählen Sie aus der Liste oben im selben Bildschirm aus:

  • Android SDK
  • Android SDK Platform

Der Rest wird nicht benötigt, da das Build-System sie selbst abruft. Fahren Sie mit der Installation fort, nachdem Sie sie ausgewählt haben.

Einen Keystore (Schlüsselwert) generieren

Gehen Sie zum Ordner, wo Sie Android-Sdk im vorigen Schritt installiert haben, benutzen Sie den Datei-Explorer und öffnen dort eine Eingabeaufforderung:

../../../_images/custom_build_open_shell.png

The actual command line to type is the following. On Linux and macOS, 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

Unter Windows sollte der vollständige Pfad zu Java angegeben werden (und & muss am Anfang der Zeile hinzugefügt werden, wenn PowerShell verwendet wird, für die reguläre cmd.exe Konsole wird dies nicht benötigt). Keine Sorge, bei Verwendung von Android Studio unter Windows ist Java mitgeliefert.

Um es klarer zu machen ist hier ein Screenshot einer Zeile, die auf der PowerShell funktioniert (durch Hinzufügen von & und dem vollständigen Java-Pfad zu keytool.exe; entferne &, wenn Sie cmd.exe verwenden). Es wird ein Pfad zur Java-Version verwendet, die mit Android Studio geliefert wird:

../../../_images/custom_build_command_line2.png

(right-click and open the image in a new tab if this appears too small)

Godot einrichten

Go to the Editor Settings and set up a few fields in Export > Android. Make sure they look like the following:

../../../_images/custom_build_editor_settings2.png

(right-click and open the image in a new tab if this appears too small)

As it can be seen, most paths are inside either the android-sdk folder you originally created, or inside the Java install. For Linux and macOS users, jarsigner is often located in /usr/bin.

With this, you should be all set.

Aktivieren der benutzerdefinierten Builds und Exports

Wenn Sie das Android-Projekt im Dialogfeld Projekt > Exportieren einrichten, muss Custom Build aktiviert sein:

../../../_images/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):

../../../_images/custom_build_gradle.png

Die erstellten Vorlagen werden anschließend automatisch verwendet, sodass keine weitere Konfiguration erforderlich ist.