Android applications using Castle Game Engine

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:

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-jdk package that will pull in (as dependencies) the best Java Development Kit version. Or install directly a package like openjdk-X-jdk.

  • On Windows, download the latest version from .

    • You should install the latest version.

    • It that fails, try the most tested version, which as of now is Java SE Development Kit 17.0.2.

    By default, it will be installed in C:\Program Files\Java\jdk-17.0.2.

The Java version required is at least 17 (this is determined by the latest Android Gradle Plugin requirements). It should not be problematic, e.g. default-jdk in latest Debian stable pulls Java 17.


Alternatively, you can skip this step (Java installation) and in the next step install full Android Studio. The complete Android Studio will already include Java version suitable for Android SDK.

For your information, the Java installation can be located by going to "File → Settings" and there to "Build, Execution, Deployment → Build Tools → Gradle → Gradle JDK". See the screenshot below.

Java location in Android Studio

If necessary, you can point to this Java location using Castle Game Engine editor (open "Preferences" dialog, go to the "Android" page, set "Java Location") or by setting the JAVA_HOME environment variable. Though in many cases it is not necessary to do this, Android tools will find Java automatically.

3.2. Install Android SDK (maybe along with Android Studio)

Download and install Android SDK.

There are two ways to do it:

  1. Install the whole Android Studio.

    This is the easier way (some configuration can be then done using GUI) and comes with useful additional GUI tools to manage virtual Android devices or mirror real (physical) Android devices. We advise this option.

    For your information (you will need this later), location of the Android SDK is visible in the Android Studio File → Settings → Languages & Frameworks → Android SDK. You need to have some project open to access this Android Studio dialog — just create a new empty project if you don’t have any.

    Android SDK location in Android Studio

    It looks like this, by default:

    • Windows: C:\Users\<my-user-name>\AppData\Local\Android\Sdk

    • Linux: ~/Android/Sdk

  2. Alternatively: Install Command line tools only (scroll to the bottom of ):

    1. Create a new directory on disk for Android SDK. Like c:/android-sdk.

    2. Unpack the command-line tools under cmdline-tools subdirectory of your chosen Android SDK directory.

    3. Move all the cmdline-tools contents under additional subdirectory latest.

    4. If effect you should have a file like c:/android-sdk/cmdline-tools/latest/bin/sdkmanager. (with additional extension .bat on Windows).

3.3. Let Castle Game Engine know your Android SDK location

The Android SDK location is the directory that contains subdirectories like cmdline-tools, tools, platform-tools. See above how to find where your Android SDK is installed.

  1. We recommend to set Android SDK location using Castle Game Engine editor "Preferences" dialog. Go to the "Android" page and adjust the "Android SDK Location" value.

    This is simple and works great if you build and run Android applications using CGE editor.

  2. Alternative: If you want to use our command-line build tool or some Android command-line tools, you can set instead the ANDROID_HOME environment variable.

    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). See also official Android documentation. 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

It’s easiest to accept the licenses using Android Studio. Just run it and proceed through the default "Standard" configuration.

Alternatively, you can accept them using command-line:


Open the terminal (press Windows key, type cmd and 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, 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.

  • Download 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 = aarch64 this 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.)

  1. 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.

  2. 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.

  3. Switch the CGE editor to build for the Android platform: use menu item "Run → Platform (To Build And Run) → Android (…​)".

  4. 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.


You could also do these steps using our command-line Build Tool:

  • Package using castle-engine package --target=android --fast --mode=debug

  • Install using castle-engine install --target=android --mode=debug

  • Run using castle-engine run --target=android --mode=debug


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 this page and create a pull request to cge-www repository.