-
Create a new directory on disk for Android SDK. Like
c:/android-sdk. -
Unpack the command-line tools under
cmdline-toolssubdirectory of your chosen Android SDK directory. -
Move all the
cmdline-toolscontents under additional subdirectorylatest. -
If effect you should have a file like
c:/android-sdk/cmdline-tools/latest/bin/sdkmanager. (with additional extension.baton Windows).
Android
Table of Contents
 |
1. Introduction
To create applications for Android you need to install some additional software. We explain everything below.
If you have problems with the procedure outlined below, please:
-
Check out our Android SDK and NDK troubleshooting and Android FAQ.
-
Consider an alternative to this: you can use our Docker image. It’s basically a light-weight virtual machine, easy to download and update and quickly run. And it contains all the software related to CGE, FPC and Android configured and tested.
-
If you get stuck, talk to us! We have a forum, Discord chat and we want to help.
2. Examples and build tool
Almost all our examples, and all new projects created by CGE editor "New Project" from one of the templates, are automatically cross-platform and can be compiled for Android. In particular:
-
You can create "New Project" from any template - 2D game, 3D game etc. You get a cross-platform application that can be build for Android.
-
examples/mobile/simple_3d_demo/- 3D world and navigation and graphic effects on Android. -
examples/mobile/achievements/- 2D animation and Google Play Games integration on Android.
Once you finish this chapter, you will be able to use use the CGE editor or command-line build tool to compile all these programs (and almost all other CGE examples) for Android.
3. Installing Android tools
3.1. Install Java
Java is required by the Android SDK. Install Java JDK (Java Development Kit).
-
On Debian or Ubuntu, you can install the
default-jdkpackage that will pull in (as dependencies) the best Java Development Kit version. Or install directly a package likeopenjdk-X-jdk. -
On Windows, download the latest version from http://www.oracle.com/technetwork/java/javase/downloads/index.html . You usually want to install the latest version, like Java SE Development Kit 17.0.2. By default, it will be installed in
C:\Program Files\Java\jdk-17.0.2.
For users who install full Android Studio below: You do not need to install Java separately. The complete Android Studio will already include Java version suitable for Android SDK. In case you will need this information (but probably not), the Java is located then in:
-
C:/Program Files/Android/Android Studio/jreon Windows -
<wherever-you-unpacked-android-studio-targz>/jreon Linux
3.2. Install Android SDK
Download and install Android SDK from http://developer.android.com/sdk/index.html .
You can:
-
Install the whole Android Studio and SDK Tools (main download on the above page). This is easier (some configuration can be then done using GUI), and thus is advised for new users.
Location of the Android SDK is visible in the Android Studio Settings -> Android SDK, on Windows it looks like
C:\Users\<my-user-name>\AppData\Local\Android\Sdk. -
Or install only the Command line tools (see the bottom of the above page):
3.3. Set ANDROID_SDK_ROOT
Set the ANDROID_SDK_ROOT environment variable. This is the directory that contains cmdline-tools subdirectory. It would be c:/android-sdk in our above example.
If you don’t know how to set the environment variable, search the Internet (e.g. these are quick instructions how to do it on various Windows versions).
Remember to close and reopen all the applications after setting the environment variable. Changing environment variables only takes effect for new applications.
3.4. Accept Android SDK license
- Windows
-
Open the terminal (press Windows key, type
cmdand press Enter) and type commands like this:cd c:/android-sdk/cmdline-tools/latest/bin/ sdkmanager.bat --licenses
- Unix (Linux etc.)
-
Open the terminal and type commands like this:
cd ~/android-sdk/cmdline-tools/latest/bin/ ./sdkmanager --licenses
You need to answer "yes" (key y) to all the license questions to let the build process automatically download the necessary Android SDK components.
3.5. Install FPC for Android (using fpcupdeluxe)
You need a special version of FPC (Free Pascal Compiler, http://freepascal.org/): a cross-compiler to Android. This means that FPC can run on your normal OS/processor (Linux, Windows, macOS…) and can produce binaries for Android. "Android" more precisely means "Android OS (based on Linux) + Android processor (32-bit arm or 64-bit aarch64)".
The easiest approach to get FPC for Android is to use fpcupdeluxe.
-
Build normal FPC and Lazarus with it. We advise picking the latest stable FPC and Lazarus versions at the time. All Android architectures are perfectly supported in latest FPC 3.2.2.
-
Install cross-compiler to Arm/Android. To do this, switch to "Cross" tab in fpcupdeluxe, select CPU =
arm, OS =android, click "Install cross-compiler". Wait a while. When it shows a message that effectively asks "Missing cross-tools, download them?" answer "yes". -
Install another cross-compiler for Aarch64 (64-bit Arm)/Android. This is done exactly like above, just select CPU =
aarch64this time. Same as above, select OS =android, click "Install cross-compiler", and confirm when it asks to download cross-tools.
Make sure CGE is using the new FPC. It is best to do this by configuring FPC and Lazarus location in CGE editor Preferences. Make sure the detected FPC and Lazarus are the ones you have just installed using fpcupdeluxe.
4. Build, install and run Castle Game Engine application for Android!
You should have everything set up now. Let’s try compiling and running our mobile demo application, in examples/mobile/simple_3d_demo/ . (You can pick almost any other CGE example if you wish, for this test.)
-
First compile and run a normal standalone version, to make sure everything is OK with your FPC installation. Just compile and run the application as usual, press F9 in CGE editor or in Lazarus to compile and run it for the default platform.
-
Connect your Android device to your PC using an USB cable, if you have one. In the next step, we will not only build, but also install and run this application on your device!
Make sure that the "USB Debugging" is turned on in the "Development Settings" on your Android phone or tablet. The official information how to do it from Google is here. In case of trouble, search the Internet about it, some devices have special quirks around it.
-
Switch the CGE editor to build for the Android platform: use menu item "Run → Platform (To Build And Run) → Android (…)".
-
And press F9. That’s it! It automatically does the build and run sequence, which in case of Android means:
-
Package the application (recompile it for both Android CPUs, and create APK with the compiled code and data).
-
Install the APK on Android device, if any device is available for the ADB tool.
-
Run the application, and capture the logs, displaying them in the editor output.
-
|
Note
|
You could also do these steps using our command-line Build Tool:
|
|
Note
|
The first Android build will take a while. That is because at the first run, we automatically download the proper components of Android SDK and NDK. Simply make sure to run the 1st build when connected to the Internet and be patient. |
5. Further steps
At this point, you have a ready APK file, which you can upload / install / run just like any other application, using any Android tool.
You can also upload your application to Google Play and release your game! Note that Google Play requires using AAB format for the uploads now, not APK. To create AAB, just switch in CGE editor menu item "Run → Package Format → Android App Bundle (AAB)" and press "Run → Package (Release to Users)".
See the Android FAQ for more information about building AAB, signing for release etc.
To improve this documentation just edit the source of this page in AsciiDoctor (simple wiki-like syntax) and create a pull request to Castle Game Engine WWW (cge-www) repository.