Home » Documentation » Manual » Platforms details
Previous: Platforms details
Next: Android FAQ
Manual

Android

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 http://www.oracle.com/technetwork/java/javase/downloads/index.html .

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

Note

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 (if some tool requires later to set e.g. JAVA_HOME), 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

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

Download and install Android SDK.

There are two ways to do it:

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

  • Alternatively: Install Command line tools only (scroll to the bottom of https://developer.android.com/studio ):

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

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:

Windows

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

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

Note

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

Previous: Platforms details
Next: Android FAQ
Manual
Documentation
  1. Recommended Tutorial: 3D Physics Fun
  2. Manual
    1. Install
    2. Build your first application
    3. Designing user interface and handling events (press, update) within the view
      1. Managing Views
    4. Viewport with scenes, camera, navigation
      1. Tutorial: Designing a 3D world
      2. Tutorial: Designing a 2D world
      3. Camera
      4. Navigation
      5. Writing code to modify scenes and transformations
      6. Behaviors
      7. Multiple viewports to display one world
      8. Expose scene elements, like children transformations as TCastleScene children
    5. User interface
      1. Text and fonts
      2. Customize loading image
      3. Custom drawn 2D controls: player HUD
    6. Editor
      1. Custom Components in Editor
      2. Components to reuse a design in other designs
    7. 2D games
      1. Sprite sheets
      2. Images
      3. Tiled maps
      4. How to render 2D games with images and sprites
    8. Physics
    9. Sound
      1. OpenAL
      2. FMOD
    10. Persistent data (user preferences, savegames)
    11. Save screen (screenshot)
    12. Network, downloading and using URLs
    13. Logging
    14. Cross-platform (desktop, mobile, consoles...) projects
      1. Data directory
      2. CastleEngineManifest​.xml
      3. Customize UI scaling, font, warmup cache by CastleSettings.xml
      4. Build Tool
      5. Touch Input
    15. Platforms details
      1. Android
      2. Android FAQ
      3. Android Services (Google Play Games and many more...)
      4. Adding New Android Services
      5. iOS
      6. iOS Services (Apple Game Center and many more...)
      7. In-App Purchases (Android, iOS)
      8. Nintendo Switch
      9. macOS
    16. Optimization
      1. Occlusion Culling
      2. Profiling Using Valgrind
      3. Detecting Memory Leaks
    17. Making rendering prettier
      1. Bump Mapping (Normal Maps)
      2. Shadow Volumes
      3. Background (skybox, sky and ground)
      4. Fog
      5. Blending
      6. Color Space (Gamma Correction)
      7. Alpha Bleeding
      8. Sketchfab
    18. Engine on a form (VCL, FMX, LCL) using TCastleControl
    19. Automatic Builds (Continuous Integration and Delivery)
      1. GitHub Actions (automatic builds for GitHub projects)
      2. GitLab CI/CD (automatic builds for GitLab projects)
      3. Docker (easily get CGE, compilers, texture compression tools)
      4. Jenkins (automatic builds by your Jenkins server)
    20. Pascal IDEs
      1. Lazarus
      2. Delphi
        1. Delphi packages
        2. Delphi for Linux
      3. Visual Studio Code
    21. Miscellaneous
      1. Which way is up?
      2. Transformation hierarchy
      3. CastleWindow Backends
      4. Threads
      5. Compiling from source
      6. Supported compilers and IDEs
      7. Coding Traps
      8. Units Map
      9. Dedicated GPU
      10. fpcupdeluxe
      11. FpMake and FpPkg
      12. License
    22. Helping in engine development
      1. Donate
      2. Roadmap
      3. Coding Conventions
    23. Deprecated: Utilities for typical 3D games
      1. Overview
      2. Loading game level
      3. Player
      4. Defining creatures and items
      5. Using creatures and items
      6. Extending creatures and items classes
  3. Creating Game Data
    1. API Reference
    2. Why Pascal?
    3. Modern Object Pascal Introduction
      1. Overview for Unity Developers
      2. Scene Graph (X3D)
        1. Conferences

          Copyright Michalis Kamburelis and Castle Game Engine Contributors.

          This webpage is also open-source and we welcome pull requests to improve it.

          We use cookies for analytics. See our privacy policy.