Android Project Components Integrated with Castle Game Engine

Michalis Kamburelis edited this page Feb 2, 2017 · 36 revisions

Android components

When you use our build tool to package your game for Android, you can easily add integration components to the project. They allow to comfortably access various Android services (from Google and other 3rd parties, like ad networks) from your Object Pascal game code using the Castle Game Engine.

Table of contents:

Declare project as "integrated"

You need to declare the project type as "integrated" to use any of the components mentioned on this page. Inside the CastleEngineManifest.xml file, add this:

<android project_type="integrated">

Inside the element you will usually add a list, for example like this:

<android project_type="integrated">
    <component name="google_play_services" />
    <component name="google_play_games">
      <parameter key="app_id" value="XXXX" />
    <component name="chartboost" />

The allowed values of project_type are:

  • base: No extra integration, the final project does not use any Java code at all. Rendering and inputs work 100%, since they don't require anything extra, and it may be enough for many games. This is the default right now.
  • integrated: We include extra Java integration code that allows to use Android project components that communicate with Object Pascal code. This opens the door for the components mentioned below.

Immediate benefits of the "integrated" project type

Merely declaring the project type as "integrated" (even without any extra components) immediately gives you:

  • Immersive mode on newer Android devices. This is a "true" full-screen mode for games on Android, where the back/home buttons are usually hidden.
  • You can open URLs (including special market:// URLs to send users to the Google Play store, e.g. to rate your application). Use the OpenURL from CastleOpenDocument unit in Pascal.
  • You can share text and links with other applications. Use ShareText from the CastleOpenDocument unit.
  • You can send Android standard on-screen notification ("toast") using OnScreenNotification from the CastleOpenDocument unit.
  • Some components (like sound and ogg_vorbis) will be added automatically to your project if the sound files are detected in your game data. So merely declaring your project type as "integrated" makes sound work on Android.



This component includes the Google Play Services library into your Android projects. It doesn't provide anything immediately useful, but it's required by some other components, like google_play_games, google_analytics, admob, heyzap.

The necessary files from Google will be automatically downloaded, along with all their dependencies, using the Gradle build system, at the first build. You only have to declare using the component by

<component name="google_play_services" />


This component enables the AdMob banner and interstitial advertisements. Use TAds class from the CastleAds unit to show and control the ads from your Pascal code, with AdNetwork set to anAdMob.


  • Using this component requires using also google_play_services.


Enable the Chartboost ads. Use TAds class from the CastleAds unit to show and control the ads from your Pascal code, with AdNetwork set to anChartboost.


  • Using this component requires using also google_play_services.
  • The core of this component is a closed-source library distributed by Chartboost. Download it from , unpack to some temporary location, and copy the lib/chartboost.jar file from the SDK to the castle_game_engine/tools/build-tool/data/android/integrated-components/chartboost/app/libs/ directory.


Enable the Game Analytics analytics of your apps. Use the TAnalytics class from the CastleAnalytics unit to initialize and send data to the analytics from your Pascal code.

  • Using this component requires using also using the google_play_services component.
  • The core of this component is a closed-source library distributed by GameAnalytics. It will be automatically downloaded using the Gradle build system on the first build, so you don't have to do anything.
  • This component requires that you increase the min_sdk_version to 10 or higher in your CastleEngineManifest.xml file. The min_sdk_version is specified at the <android> element.


Enable the Giftiz integration. Your app notifies Giftiz when the user finished a mission inside your game, and Giftiz gives users (real!) gifts. See website for more information, and contact them to get the necessary SDK and partner id.

Use TGiftiz class from the CastleGiftiz unit to control the integration from your Pascal code. Send the "mission complete" message to Giftiz by calling TGiftiz.MissionComplete;. Display Giftiz button on top of your game UI using the TGiftizButton UI component.


  • The core of this component is a closed-source library distributed by Giftiz in their SDK.
    • Unpack the Giftiz SDK to a temporary directory.
    • Copy the GiftizSDKLibrary/libs subdirectory to the castle_game_engine/tools/build-tool/data/android/integrated-components/giftiz/app/libs.
    • Copy the GiftizSDKLibrary/res subdirectory to the castle_game_engine/tools/build-tool/data/android/integrated-components/giftiz/app/src/main/res. Double-check the path: the res goes inside the app/src/main/, while the libs are in higher-level app folder.
    • Copy the button UI images: from GiftizSDK_1.5.0/Customize/Border_white copy the png files to your game's data/giftiz/ subdirectory. There's an alternative set of images in Border_no, and some customization of these images is allowed (see Giftiz SDK for details). Our Pascal integration will automatically load and use these images to display Giftiz button.
  • You need to specify Giftiz partner id for integration. Initially this is TEST_PARTNER_KEY, and if you're accepted --- Giftiz will send you your real partner id. You declare it in your CastleEngineManifest.xml file like this:

    <android project_type="integrated">
        <component name="giftiz">
          <parameter key="partner_key" value="TEST_PARTNER_KEY" />


Enable the Google Analytics analytics of your apps. Use the TAnalytics class from the CastleAnalytics unit to initialize and send data to the analytics from your Pascal code.


  • Using this component requires using also the google_play_services component.
  • Recent Google Analytics require you to use a special google-services.json file in your project.

    • On this page click "Get a Configuration File"
    • On a form that appears, add "Analytics" service to your application, selecting proper Google Analytics account parameters.
    • Download google-services.json from the form above.
    • Place the contents of this google-services.json file inside the CastleEngineManifest.xml as the parameter of the google_analytics, like this:

      <component name="google_analytics">
        <parameter key="game_services_json">
        "configuration_version": "1"


This component enables the In-App Purchases through Google Play. The is the most popular way to purchase stuff on Android. Use TInAppPurchases class from the CastleInAppPurchases unit to handle the purchases from your Pascal code.


Enable the Google Play Games Services. Use the TGooglePlayGames class from the CastleGooglePlayGames unit in Pascal to initialize and use it, for example to sign-in, send scores and achievements, view achievements and leaderboards, load and save savegames in the cloud.


  • Using this component requires using also google_play_services
  • You must create a project in "Game Services" section of the "Google Developer Console". This will give you a special "app_id" for your project. In order for the integration to work, you need to specify this app_id in our CastleEngineManifest.xml, like this:

    <android project_type="integrated">
        <component name="google_play_services" />
        <component name="google_play_games">
          <parameter key="app_id" value="PASTE-APP-ID-HERE" />

    After this, you need to call from Pascal code GooglePlayGames.Initialize to connect to Google Play Games when you want (usually, at the beginning of your game: from TCastleApplication.OnInitializeJavaActivity).


Enable the Helpshift, a mobile-friendly support system (submitting issues, chat with support, FAQ). Use the trivial THelpshift class from the CastleHelpshift unit to show the Helpshift activities from your application.


  • Create an account on , to get the necessary keys for your project. Use them when declaring the component parameters in CastleEngineManifest.xml:

    <component name="helpshift">
      <parameter key="api_key" value="xxx" />
      <parameter key="domain" value="" />
      <parameter key="app_id" value="xxx_platform_xxx" />
  • The Helpshift library is automatically downloaded at the first build using Gradle, so you don't have to do anything yourself.

  • Make sure you compile with Android SDK platform 23 or higher (already the default now) and have min_sdk_version >= 14 in your CastleEngineManifest.xml. See the . This page also says you need the target_sdk_version >= 23, but I found that older versions work too.


Enable the Heyzap advertisements. Use TAds class from the CastleAds unit to show and control the ads from your Pascal code, with AdNetwork set to anHeyzap.


  • The core of this component is a closed-source library distributed in Heyzap SDK.
    • Download the SDK from (select in Step 1 whether you want to use beta or not, and then in Step 2. Download the SDK click on SDK link).
    • Unzip the SDK to a temporary location.
    • Copy the jar file from SDK android-sdk/heyzap-ads-sdk.jar into castle_game_engine/tools/build-tool/data/android/integrated-components/heyzap/app/libs/heyzap-ads-sdk.jar.

Optional notes to use Heyzap mediation: You can use Heyzap integration (SDK) to get ads from many ad networks --- not only from Heyzap own network, but also from AdMob, Chartboost and many more. To do this, you will need to setup the integration in your Heyzap dashboard. Also you will need to follow the instructions on to add additional networks SDKs. Select the additional networks on that page, and follow the instructions:

  • Usually, Heyzap docs will instruct you to download some additional SDK. Do as it says, and place the .jar and .aar files into the ..../integrated-components/heyzap/app/libs/ directory, alongside the Heyzap jar.
  • For every .aar file that you have added, add appropriate <dependency> line to the ..../integrated-components/heyzap/app/build.gradle file. Like this:

    <dependency>compile(name:'AudienceNetwork', ext:'aar')</dependency>
    <dependency>compile(name:'unity-ads', ext:'aar')</dependency>
  • Make the necessary modifications in the ..../integrated-components/heyzap/app/src/main/AndroidManifest.xml. Make sure it contains only (and exactly!) the activities/permissions that Heyzap docs show you.

  • Note for AdMob: Using AdMob requires that you also use "google_play_services" component. And you should add to the ..../integrated-components/heyzap/app/build.gradle file these lines:

    <dependency>compile ''</dependency>
    <dependency>compile ''</dependency>
  • Note: that some ads SDK may require increasing the min_sdk_version in your CastleEngineManifest.xml. You will get a clear error message when building APK in case this is necessary. Currently, Facebook Ads (Facebook Audience Network) requires min SDK >= 11.
  • Note: when you use Heyzap to integrate with some 3rd-party ad network (for example with Chartboost), then you should not add a component in CastleEngineManifest.xml to also directly interact with this network (in this example "chartboost"). That is: include *only** the heyzap component in CastleEngineManifest.xml*. Otherwise the SDK underneath (like chartboost) will be initialized and handled by two code paths (one directly in our Java code, and one inside Heyzap jar), which can lead to various troubles.
  • To test your integration, call TAds.StartTestActivity(anHeyzap) in your Pascal code. This will show a special activity where you can test whether the connection with your 3rd-party networks works OK. Optional, but highly suggested!


Enable the sound component on Android. There is no need to include this component explicitly, it is automatically added if your game depends on a sound library. Which in turn may be done by declaring <dependency name="Sound" /> in CastleEngineManifest.xml, but usually it's automatically detected when the build tool notices a sound file inside your data.


Enable the StartApp ads. Use TAds class from the CastleAds unit to show and control the ads from your Pascal code, with AdNetwork set to anStartApp.


Enable the OggVorbis sound format on Android.

There is no need to include this component explicitly, it is automatically added if your game depends on "OggVorbis". Which in turn is automatically detected when the build tool notices an .ogg file inside your data, although it can also be explicitly requested by declaring <dependency name="OggVorbis" /> in CastleEngineManifest.xml.

In effect, loading OggVorbis sound files in your Android games just works -- you only need to make sure your Android project_type is set to "integrated".

We use very fast open-source OggVorbis implementation called Tremolo, see . You can compile Tremolo in low-precision mode ( to get more efficiency (decoding will be faster, less CPU hungry), although then the quality is quite horrible in my tests.

Note that on Android, the sound engine (with OpenAL underneath) has to be paused / resumed when user switches between applications. If you play some music, and you want resuming to start it again --- you need to register you callback on SoundEngine.OnOpenClose to handle this situation. If you play music using TMusicPlayer, this is taken care of automatically.


Allows to vibrate the device. Use the Vibrate procedure from CastleOpenDocument unit to cause vibration from Object Pascal code.

It's easy to add more components!

It's very easy to add your own Android components, if you need to integrate with some Android library not covered above. Simply create your component inside the castle_game_engine/tools/build-tool/data/android/integrated-components/xxx/ directory. The files there are copied to the final Android project, expanding macros inside. Most of the files are simply copied (but without overwriting), but some files are merged in a special way:

  • AndroidManifest.xml of each component is merged with the main AndroidManifest.xml in a smart way, only adding the new permissions and new elements/attributes inside the .
  • build.gradle files inside the components have a special XML syntax. See the example components like helpshift. They are merged into the final (non-XML) build.gradle file in a smart way.
  • Each component may also insert a snippet of Java code to the file. This is typically used to initialize the component-specific Java class, like

    components.add(new ComponentStartApp(this));

When developing new components, it's a good idea to to package your games with --verbose --leave-temp command-line parameters, like

castle-engine package --os=android --cpu=arm --verbose --leave-temp

This allows to inspect (in a temporary directory that is listed in the output) what the final, merged project looks like.

To communicate with the components from the Object Pascal code, use the CastleMessaging unit. Our units like CastleAds or CastleGooglePlayGames are simply thin "wrappers" using CastleMessaging unit under the hood --- see at their sources to know how it works! A detailed explanation is also available in this forum post: .