Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
You can create games (and other applications) for Android using our Castle Game Engine.
- Overview and examples
- Installing Android tools
- Android FAQ
Overview and examples
The description how to create a cross-platform project, that can work on Android (and other platforms) is in the manual: https://castle-engine.io/manual_mobile.php . This page describes tools you need to install to make the building for Android work.
The engine sources include many examples, and many of them are cross-platform and can be tested on Android. In particular, check out:
- examples/mobile/simple_3d_demo/ - shows 3D world and navigation and graphic effects on Android,
- examples/2d_dragon_spine_android_game/ - shows 2D animation and Google Play Games integration on Android,
- https://castle-engine.io/darkest_before_dawn.php - a complete 3D game, with full source code, for Android and standalone, using our engine.
Use the Build Tool to easily compile these programs for Android (or other platforms --- they all can be compiled as standalone games too!). But first be sure to install the Android tools described below. They will be called by the Build Tool under the hood.
Installing Android tools
To be able to develop Android application, you need some tools from Google, and you need FPC that can compile code to an Android.
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 like
- On Windows, download the latest version from http://www.oracle.com/technetwork/java/javase/downloads/index.html . Just google for "Java JDK download" if this link doesn't work:) You usually want to install the latest version, like Java SE Development Kit 8uXXX. By default, it will be installed in
Warning: do not use Java SDK version >= 9 now, use Java version 8. Java version 9 has problems when used with the older version of Gradle (resulting in "Could not determine java version from '9.0.4'" error message), but upgrading Gradle in turn requires upgrading other stuff in our Android toolchain. Michalis is working on it (in branch https://github.com/castle-engine/castle-engine/tree/upgrade-gradle ), in the meantime please stick to Java <= 8.
You can have multiple Java versions installed, but then make sure that the correct one (<= 8) is indicated by the $PATH and $JAVA_HOME environment variables (if you set them).
On Debian and derivatives, you can switch between installed Java versions using a command like
sudo update-java-alternatives -l; sudo update-java-alternatives -s java-1.8.0-....
For Windows users who install full Android Studio: You do not need to install Java separately. The complete Android Studio will already include Java (Java 8, which is good version for us). You will want to set
JAVA_HOME environment variable later to something like
C:/Program Files/Android/Android Studio/jre.
Install Android SDK
Download and install Android SDK from http://developer.android.com/sdk/index.html .
For Windows users who install full Android Studio: The Android SDK and NDK are automatically managed by the Android Studio. Location of Android SDK is visible in the Android Studio Settings -> Android SDK, it looks like
C:\Users\<my-user-name>\AppData\Local\Android\Sdk. The NDK will be installed there too, in
Adjust environment after installing SDK
$ANDROID_HOMEenvironment variable, to point to your Android SDK directory. This is recognized by both our build tool, and some Android tools.
- Consider adding to
<android-sdk>/platform-tools/directory. In Castle Game Engine > 6.0.2, this is not necessary (engine doesn't need it), but still advised: it allows you to call
adbon the command-line easily, which is often useful.
$JAVA_HOMEenvironment variable, to point to your newly installed Java Development Kit (JDK). This is required by the Android build tools.
If you don't know what an "environment variable" is, google "how to set environment variable in windows/linux/..." :) Remember to reopen the relevant application (e.g. close and reopen the terminal) to see the newly set environment variables.
Install Android SDK components
Run the Android SDK Manager, and install some components:
In newer Android SDK (at least 2.3.1) the SDK Manager is a part of the Android Studio.
Run Android Studio, if you see a wizard prompting you to create new project -- cancel it, then choose Configure -> SDK Manager.
Make sure that it knows the correct path to the Android SDK. You may need to Edit the SDK location if you installed to a non-standard path.
On the "SDK Platforms" tab (1st tab) select "Android 6.0 (Marshmallow) - API 23" (be sure to use this exact version). Check "Show Package Details" at the bottom to see more, make sure that inside the "Android 6.0 (Marshmallow) - API 23" section the "Android SDK Platform 23" and "Google APIs" subcomponents are selected.
On the "SDK Tools" tab (2nd tab), select the "Android SDK Build-tools" version 23.0.2. Check "Show Package Details" at the bottom to be able to select the exact "Android SDK Build-tools" version. Be sure to install this exact version (not earlier, not later). You can install other versions too, they don't conflict, but you must install this exact version too.
Also on the "SDK Tools" tab (2nd tab), select "NDK".
Also on the "SDK Tools" tab (2nd tab), from the section "Support Repository" (usually at the bottom of the list), make sure "Android Support Repository" and "Google Repository" are selected.
Click OK, choose Accept at the license question.
In older Android SDK, it was a program called just
tools/subdirectory. You can just run
androidfrom the command-line, if you set up the $PATH as instructed above. On Windows, you can also run it by executing SDK Manager.exe from the main SDK directory.
- From the "Tools" section, install the "Android SDK Build-tools" version 23.0.2. Be sure to install this exact version (not earlier, not later). You can install other versions too, they don't conflict, but you must install this exact version too.
- From the section "Android 6.0 (API 23)" (again, be sure to use this exact version), install the "SDK Platform" and "Google APIs" subcomponents. Note that this does not set the minimal Android version of the resulting applications. The final Android games created using our engine can work even with Android 2.2 (version 8).
- From the section "Extras" (usually at the bottom of the list), install "Android Support Repository" and "Google Repository".
If you prefer to use the command-line, you can alternatively download only Android SDK command-line tools. Set
$ANDROID_HOMEenvironment variable, and then execute
tools/bin/sdkmanager --install 'platforms;android-23' 'extras;google;google_play_services' 'build-tools;23.0.2' 'extras;android;m2repository'
Remember to use apostrophes as shown above. You will have to download NDK separately in this case.
If you know what you're doing, you can actually use other versions of SDK components (other versions of "SDK Platform" and "Android SDK Build-tools"). You will need to declare them on a per-project basis in
CastleEngineManifest.xml, see Build Tool. But it's probably easiest if you use their default versions at the beginning.
Install Android NDK
Install Android NDK from http://developer.android.com/tools/sdk/ndk/index.html .
For Windows users who install full Android Studio: The Android NDK installation is managed by Android Studio. The NDK will be installed under the
ndk-bundle subdirectory of Android SDK. Of course, if you want you can alternatively install NDK separately, without Android Studio.
Adjust environment after installing NDK
$ANDROID_NDK_HOMEenvironment variable, to indicate the directory of NDK. (Even if it's inside the
<android-sdk>/ndk-bundledirectory. Our build tool can figure it out (testing
$ANDROID_HOME/ndk-bundle), but Google tools can't, they need
- (Not necessary if you will use fpcupdeluxe to get cross-compiler using a friendly GUI) On $PATH: put the NDK subdirectory containing arm-linux-androideabi-as for your platform, for example
.../android-ndk-XXX/toolchains/arm-linux-androideabi-4.9/prebuilt/linux-x86_64/bin. Where "
arm-linux-androideabi-4.9" is the Android platform version, just choose latest "
arm-linux-androideabi-XXX". And the "
prebuilt/linux-x86_64" corresponds to the real OS where you are now (you probably have only one subdirectory inside "
prebuilt/" anyway, the one for which you downloaded NDK). Use "
linux-x86_64" if you work on Linux 64-bit, adjust for other systems as necessary. The goal is to have programs like
arm-linux-androideabi-ldavailable on your $PATH.
- Consider adding to
$PATHthe main NDK directory (with
ndk-gdbtools inside). In Castle Game Engine > 6.0.2, this is not necessary (the engine build tool doesn't need it), but it may be comfortable for you anyway (if you plan to use command-line
Test Android SDK + NDK before going further!
It is a good idea at this point to test compiling (and deploying to your actual Android device) some example code from the Android NDK. This allows to make sure that you configured everything correctly, before you start playing with combining Object Pascal code + Android.
Please do not skip this step. It is easy to make a mistake in the installation procedure above (very possible if you have never used Android SDK or NDK before). Sometimes, there's also a real bug / problem in the Android SDK or NDK (google usually has the solution). Detecting (and fixing) these problems here (not later) will save you a lot headaches!
For example compile and install (on an Android device, typically connected through USB) the "hello-gl2" demo from Android NDK.
Download it from GitHub, like this:
git clone https://github.com/googlesamples/android-ndk android-ndk-samples
Make sure you have installed the Android "SDK Platform" and "Android SDK Build-tools" required by hello-gl2 sample. To find what versions are necessary, look inside android-ndk-samples/hello-gl2/app/build.gradle file:
- Line like
compileSdkVersion = 25means that you need to install Android "SDK Platform" in version 25 (not earlier, not later). Along with "Android SDK Build-tools" with the same major version.
- Install them using the Android SDK tool, if needed, just like described above in the "Install Android SDK components" section.
- Line like
Compile the example code by this command-line:
cd android-ndk-samples/hello-gl2/ # On Windows platforms, type this command: gradlew.bat assembleDebug # On Mac OS and Linux platforms, type these commands: chmod +x gradlew ./gradlew assembleDebug # See https://developer.android.com/studio/build/building-cmdline.html . # The first run will take a long time, as gradle downloads it's components. # This should create a file app/build/outputs/apk/app-debug.apk # Check that your device is connected, enable "USB debugging" and authorize it if needed adb devices # Install the application (use -r to reinstall) adb install app/build/outputs/apk/app-debug.apk # Or install using gradle: ./gradlew installDebug
And then run the resulting application (it is called "GL2JNI") on your device. It will work equally well on a real Android device, or in the Android emulator.
Really, really make sure that you installed the right versions of SDK Platform and Android SDK Build-tools. You need them both, and both must have the exact required versions (not earlier, not later).
In case of errors about
libz.so.1(resulting in later errors about Exception in thread "png-cruncher...) on Linux 64-bit, see here: http://stackoverflow.com/questions/29241640/error-unable-to-run-mksdcard-sdk-tool . Install additional libraries as needed.
The Android NDK for 32-bit Windows has a known error in version r12b, see https://github.com/android-ndk/ndk/issues/139 . The clang binaries are for 64-bit architecture. It will prevent compiling the NDK samples (not related to CGE...). This should be fixed in next NDK release. An easy fix for now is to go to "ndk\toolchains\llvm\prebuilt\windows\bin" directory and:
- rename clang.exe -> clang_64.exe (or just remove it)
- rename clang_32.exe -> clang.exe
- rename clang++.exe -> clang++_64.exe (or just remove it)
- copy clang.exe -> clang++.exe (yes, just copy to a new name, this is the same executable).
The error Could not find tools.jar usually means you did not set JAVA_HOME correctly (to point to JDK).
If you get errors when executing
/usr/local/android/android-sdk-linux/build-tools/23.0.2/aidlon 64-bit (x86_64) Linux:
That is because Google distributes them as compiled for a 32-bit (i386) Linux system. Install some additional libraries to make them work. On Debian:
apt-get install libc6-i386 lib32stdc++6 lib32z1
(In general, old build-tools are distributed only for Linux 32-bit, and new build-tools are distributed only for Linux 64-bit. Google doesn't provide alternatives for both architectures here.) See https://stackoverflow.com/questions/24158727/android-sdk-aapt-error-libstdc-so-6-cannot-open-shared-object-file .
FPC for Android
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, MacOSX...) and can produce binaries for Android. "Android" more precisely means "Android OS (based on Linux) + Android processor (usually ARM)".
You need to use FPC >= 3.0.2 for Android compilation. Reasons: The PIC support for Android libraries is not implemented in earlier FPC versions, and it's required when using Android SDK >= 23, see http://wiki.freepascal.org/Android .
As an alternative, below we describe how to manually compile latest FPC 3.3.1 for Android:
- Make sure you have installed the latest stable FPC version (3.0.2 at the time of this writing), it is required to compile (bootstrap) new FPC version.
- Get and compile FPC from SVN.
Here'a an example how to do it from the command-line.
svn checkout http://svn.freepascal.org/svn/fpc/trunk/ # Of course adjust INSTALL_PREFIX below. # -CfVFPV3 is necessary for hard floats, this way the engine works much faster. make clean crossall crossinstall OS_TARGET=android CPU_TARGET=arm CROSSOPT="-CfVFPV3" INSTALL_PREFIX=$HOME/installed/fpc/android # It is also advised to compile and install a "normal" FPC binaries and units, # not cross-compiling, # for compiling to your normal OS with the same FPC version. make clean all install INSTALL_PREFIX=$HOME/installed/fpc/android # On Unix (not on Windows), this is also useful for comfort: cd $HOME/installed/fpc/android/bin ln -s ../lib/fpc/3.3.1/ppcrossarm . ln -s ../lib/fpc/3.3.1/ppc386 . # On Windows, it is useful to copy some helper binaries from the last stable FPC release. # These include: # - windres # - gcc, cpp
- See http://wiki.freepascal.org/Android for links to more info.
- In the same way, you could compile FPC 3.0.2 cross-compiler for Android (start with FPC 3.0.0, previous stable version, to "bootstrap" the 3.0.2 compiler).
Add paths to NDK dirs to your ~/.fpc.cfg (see http://www.freepascal.org/docs-html/user/usersu10.html if you're unsure where's your configuration file; you can create a new one using "fpcmkcfg" program). This way FPC will find the correct NDK tools to link your programs:
#ifdef ANDROID #ifdef CPUARM -Fl/usr/local/android/android-ndk-current/platforms/android-23/arch-arm/usr/lib/ #endif #ifdef CPU386 -Fl/usr/local/android/android-ndk-current/platforms/android-23/arch-x86/usr/lib/ #endif #ifdef CPUX86_64 -Fl/usr/local/android/android-ndk-current/platforms/android-23/arch-x86_64/usr/lib/ #endif #endif
Also, double check that your FPC config does not contain any weird -XP option. FPC can correctly determine it at runtime, and having it set in config file does more harm than good --- unless you know what it does and why you use it.
Test compiling and running mobile demo
You should have everything set up now. Let's try compiling and running our mobile demo application, in
First compile and run a normal standalone version, in simple_3d_demo_standalone.lpr . Just compile and run it as usual, using Lazarus or "simple_3d_demo_standalone_compile.sh" script (which simply executes FPC from command-line with proper options).
Then compile a standalone version using our Build Tool, by calling
Now compile the Android application using our Build Tool, by caling
castle-engine compile --os=android --cpu=arm
This should create
libsimple_3d_demo.sofile, using FPC for Android and Android NDK tools.
If all is well, go one step further, create an Android package using
castle-engine package --os=android --cpu=arm
This recompiles a release version and creates a ready
simple_3d_demo.apkfile that you can install on your Android device.
You can install and run the apk if your Android phone is connected to your computer (through USB cable).
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 on https://developer.android.com/studio/run/device.html (ignore mentions of
build.gradlethere, the build tool hides it from you). In case of trouble, search google about it, some devices have special ways to enable it. Keep trying until
"adb devices"shows your device --- it is necessary to make further commands work.
adb devices # should show your device in response castle-engine install --os=android --cpu=arm castle-engine run --os=android --cpu=arm
These commands install and run the application using Android SDK tools underneath. They show the log of your running application, which is very useful for testing.
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 it to Google Play and release your game! Go for it!:)