Android

Michalis Kamburelis edited this page Aug 28, 2018 · 68 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: 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.

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 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 C:\Program Files\Java\jdk1.8.0_XXX.

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 ndk-bundle subdirectory.

Adjust environment after installing SDK

  • Set $ANDROID_HOME environment variable, to point to your Android SDK directory. This is recognized by both our build tool, and some Android tools.
  • Consider adding to $PATH the <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 adb on the command-line easily, which is often useful.
  • Set $JAVA_HOME environment 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.

      Android SDK Manager 1

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

      Android SDK Manager 2

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

      Android SDK Manager 3

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

      Android SDK Manager 4

    • Click OK, choose Accept at the license question.

  • In older Android SDK, it was 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.

    • 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_HOME environment 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

  • Set $ANDROID_NDK_HOME environment variable, to indicate the directory of NDK. (Even if it's inside the <android-sdk>/ndk-bundle directory. Our build tool can figure it out (testing $ANDROID_HOME/ndk-bundle), but Google tools can't, they need $ANDROID_NDK_HOME.)
  • (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-ld available on your $PATH.
  • Consider adding to $PATH the main NDK directory (with ndk-build and ndk-gdb tools 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 ndk-gdb).

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 = 25 means 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.
  • 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 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/aidl on 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 .

The easiest way to get a cross-compiler for Android is to use fpcupdeluxe. I advise it, instead of the manual process described below. Use fpcupdeluxe to get FPC 3.0.4 or 3.3.1 (trunk) for 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 examples/mobile/simple_3d_demo/ .

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

  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 libsimple_3d_demo.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 simple_3d_demo.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!:)

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.