Android

Michalis Kamburelis edited this page Jan 24, 2017 · 30 revisions

You can create games (and other applications) for Android using our Castle Game Engine.

Overview and examples

The description how to create a cross-platform project, that can work on Android (and other platforms) is in the manual: http://castle-engine.sourceforge.net/tutorial_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/android/android_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,
  • http://castle-engine.sourceforge.net/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.

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 SDK. Or install directly a package like openjdk-X-jdk.
  • On Windows, download the latest version from http://www.oracle.com/technetwork/java/javase/downloads/index.html . Just google for "Java SDK download" if this link doesn't work:)

Note: previous versions of this wiki mentioned also the need to install ant. It's no longer used. We have migrated to 100% use the new Google build system using the Gradle. It will be automatically downloaded at the first build, so there's no installation necessary.

Install Android SDK

Install Android SDK from http://developer.android.com/sdk/index.html .

You can choose the version with or without Android Studio, it doesn't matter for our needs. When developing games using our engine, you will only use Object Pascal (it is not necessary to write a single line of Java). However, if you want to really understand Android development, I recommend you first create and deploy a simple Java application using the SDK. At least compile a "Blank Activity" using Android Studio in SDK, or (even better) follow http://developer.android.com/training/basics/firstapp/index.html . This will help you understand and test how Android SDK works, which may be useful later if you encounter trouble.

Adjust environment after installing SDK

  • On $PATH: put .../sdk/tools/ and .../sdk/platform-tools/
  • You can (but may not have to, depends on your system and configuration) also set $JAVA_HOME environment variable, to point to your newly installed JDK.
  • You can (but may not have to) set $ANDROID_HOME environment variable, to point to your .../sdk/ dir.

Install Android SDK components

Run the Android SDK tool. It's a program called just android in SDK tools/ subdirectory. You can just run android from 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.

You will need to install some components:

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

Adjust environment after installing NDK

  • Set $ANDROID_NDK_HOME environment variable, to indicate the directory of NDK.
  • 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-ld available on your $PATH.
  • Also on $PATH: add to the $PATH the main NDK directory, with "ndk-build" tool (this is expected by our Build Tool).

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 = 23 means that you need to install Android "SDK Platform" in version 23 (not earlier, not later).
    • Line like buildToolsVersion = 23.0.2 means that you need the version 23.0.2 of the "Android SDK Build-tools".
    • Install them using the Android SDK tool, if needed, just like described above in the "Install Android SDK components" section.
  • 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.

Common problems:

  • 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 be 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).

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)".

To compile latest FPC 3.1.1 for Android:

  • Make sure you have installed the latest stable FPC version (3.0.0 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.1.1/ppcrossarm .
ln -s ../lib/fpc/3.1.1/ppc386 .

# On Windows, it is useful to copy some helper binaries from the last stable FPC release (3.0.0).
# These include:
# - windres
# - gcc, cpp

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/home/michalis/sources/android/ndk/platforms/android-23/arch-arm/usr/lib/
#endif
#ifdef cpu386
-Fl/home/michalis/sources/android/ndk/platforms/android-23/arch-x86/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 android_demo

You should have everything set up now. Let's try compiling and running our android_demo application, in castle_game_engine/examples/android/android_demo/ .

  1. First compile and run a normal standalone version, in androiddemo_standalone.lpr . Just compile and run it as usual, using Lazarus or "androiddemo_standalone_compile.sh" script (which simply executes FPC from command-line with proper options).

  2. Then compile a standalone version using our Build Tool, by calling

    castle-engine compile
    
  3. Now compile the Android application using our Build Tool, by caling

    castle-engine compile --os=android --cpu=arm
    

    This should create "libandroiddemo.so" file, using FPC for Android and Android NDK tools.

  4. 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 xxx.apk file that you can install on your Android device.

  5. 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.gradle there, 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!:)