Mobile improvements (with FPC): local notifications on Android, consent for AdMob, better iOS savegame location

Posted on

Local notifications example
Local notification on Android

Last news post was all about mobile development with Delphi. Let’s follow this with a list of improvements for mobile development with FPC!

  1. We have a new Android service local_notifications to send notifications.
    • An example showing the capabilities of it is in examples/mobile/local_notifications.

    • The API is nice and simple.

    • Big thanks to Hamid reza Kabiri for implementing this!

    • Note: These are local notifications, which means you send them when your application is running (to display immediately or after a specified delay). Contrast this with push notifications, which require a backend that determines the notification time — this would be a separate service.

    • Note: This service is for sending notifications using FPC. If you use Delphi, use FireMonkey API for notifications.

  2. Our AdMob service on Android now supports asking the user for consent before showing ads.

    • The service follows the Google-recommended pattern for asking for consent using User Messaging Platform. So the dialog looks consistent and non-surprising to users.

    • The change is backward compatible, so if you want to keep using it as before — you technically can. But note that asking for consent is legally required in Europe (European Economic Area and the UK).

    • This was again done by Hamid reza Kabiri. Big thanks!

  3. All Android services can automatically bump Android’s “min SDK version”. This allows you to “just use” services like admob or game_analytics, without additional tweaking of the manifest file.

  4. We have updated Gradle version used by our Android build files, to support Java >= 25 for Android building.

  5. On iOS, we change the castle-config:/ location to one recommended by Apple. Read on for details.

Change of iOS savegame location

Only for iOS applications built with FPC: We change where we store configuration files.

This applies to user preferences, savegames, etc. — everything you access using configuration files castle-config:/xxx URLs.

  • Previously, we stored config files (castle-config:/ URLs) in NSLibraryDirectory.
  • Now, we store them in NSApplicationSupportDirectory.

The reason for the change: the new location follows Apple recommendations. See Apple “File System Basics” -> “Where You Should Put Your App’s Files”:

“Put app-created support files in the Library/Application support/ directory. In general, this directory includes files that the app uses to run but that should remain hidden from the user. This directory can also include data files, configuration files, templates (…)”.

The change is aligned with what happens with Delphi. We determine iOS preferences location for Delphi using different code but we made sure it is effectively calculating the same. See Objective-C code doing the equivalent for FPC. So your iOS applications will read/write the same configuration, no matter which compiler you use.

The new directory is in practice a subdirectory of the old one: it is <sandbox>/Library/Application Support/, while previously it was <sandbox>/Library/.

Backward compatibility:

The change itself could be a trivial 1-line change, but we need to do more work to be backward compatible. If you have an existing application, using CGE and FPC, on iOS, and you have saved some configuration -> if you rebuild your application with the new engine, it will still open the old configuration.

The backward compatibility mechanism should “just work” if all you do is read / write config files using castle-config:/... URLs. Opening castle-config:/... URLs with engine API, testing with UriExists -> will just work.

To account for edge-cases, and people who write their own Objective-C code, let us describe the details of how the compatibility was done:

  • The library now exposes an additional routine, CGEApp_SetFallbackConfigDirectory.

  • Our Objective-C code passes there the old config location.

  • From your application, if you try to open the URL at castle-config:/, or check for existence using UriExists, we will first check the new config location, and then (if set) we will use the old location provided to CGEApp_SetFallbackConfigDirectory. This happens when ResolveCastleConfigUrl is called with 2nd parameter UseFallbackIfNotExists set to true.

  • Nothing else is using the fallback config directory. Writes will always go to the new, proper config directory. So if you open and save a savegame on iOS, created with the old application version, the new application version will put it in the new location. Further reads will ignore the old file in the old location, since the file will exist in the new location. This should be invisible to the user on iOS (<sandbox>/Library/ is not visible in any application), so it should not cause problems.

Possible known gaps:

  1. Using FindFiles with castle-config protocol, like FindFiles('castle-config:/savegames/*.sav', ...) will not see the old savegames on iOS (in a fallback directory). If you need this to work:
    1. Avoid FindFiles with castle-config protocol on iOS with FPC. Use UriFileExists instead, e.g. check a list of possible savegame filenames. To be clear: You only need to be careful about this if you have users that have savegames in the old location (made with an old engine version). This concern doesn’t apply to new applications made with CGE for iOS.

    2. If the above advice is difficult, a fallback is to hack engine tools/build-tool/data/ios/xcode_project/cge_project_name/OpenGLController.m to use NSLibraryDirectory again (instead of NSApplicationSupportDirectory) for the config location. This is brutal but simple and effective: it gets you back to the old state, and it’s just a 1-line change. And let us know — so we can design a proper upgrade plan!

  2. If you relied on UriToFilenameSafe to convert castle-config protocol on iOS with FPC, it will not see the fallback file. We don’t know in which context you use UriToFilenameSafe, so it only resolves to the new config location. If this is a problem, our advice:

    1. First of all, don’t use UriToFilenameSafe — operate on URLs as much as possible, provide URLs to all CGE routines.

    2. Use ResolveCastleConfigUrl with 2nd parameter UseFallbackIfNotExists set to true.

Please contact us if this is causing any problems for you — we will propose solutions 🙂

As always, we hope you have fun developing games using Castle Game Engine and we appreciate your donations.

Comments on the forum ➤

Developing games for Android and iOS using Delphi and Castle Game Engine

Posted on

Castle Game Engine with Delphi on Android and iOS: gyroscope, accelerometer, camera demos
Castle Game Engine with Delphi on Android and iOS: gyroscope (from youtube movie)
Castle Game Engine with Delphi on Android and iOS: walking adventure (3D game)
Castle Game Engine with Delphi on Android and iOS: platformer

We’re proud to officially announce that Castle Game Engine now supports Android and iOS platforms when used with Delphi! Download the engine and try it out right now.

We wrote extensive documentation about our mobile support with Delphi. Here’s the short version:

Things just work. Open any example/project made with the engine, add Android/iOS platform, and build+deploy it for your phone just as you would any other FireMonkey project.

The above documentation looks like a small book at this point, and that’s already after 2 phases of proofreading and shortening, so you will have to bear with it 🙂 Consult it when you run into problems or have questions.

We also made a video demonstrating it all: Using Castle Game Engine + Delphi to develop Android and iOS applications, accessing phone sensors.

A short overview of the above resources:

  • Rendering: We share the OpenGL ES rendering context with FireMonkey. You can use either TCastleWindow (if you want to render everything with our engine) or TCastleControl (if you want engine rendering to be a rectangle on a FireMonkey form you design).

  • In both cases, for Delphi, your application is just a FireMonkey application. You configure SDKs and the connection to Android and iOS (through macOS) just like for any other FireMonkey application. We document it here.

  • Input with multi-touch works. (If you use TCastleControl, be sure to call TCastleControl.MultiTouchOnForm.)

  • Audio works. (Without 3D spatialization yet, but it is on our roadmap.)

  • Our URLs to access data and everything else work. TCastleDownload works.

  • A nice plus of FireMonkey (FMX) integration is that you can use existing non-visual FireMonkey components for some cool things: camera, location service, accelerometer, gyroscope. These are all available for your games with Delphi. We have ready examples showing this, and our video shows them too.

  • We have tested and made sure it works even with older Delphi versions. Android is supported as far back as Delphi 10.4.0 with Patch 1 (but Delphi 10.4.2 is heavily recommended). See reasons and details behind Delphi version requirements.

  • While you can do everything from the Delphi IDE, you can also compile, package, run and more from our editor or command-line build tool. This has some advantages, e.g. you will see live logs from your running Android application. Command-line building is also of course useful with CI and our build tool lets you trivially switch between Delphi and FPC.

  • To be clear: We already support Android and iOS with FPC, this has been available for years, and nothing changes in this regard. We focus in this announcement on new Delphi possibilities, but the engine core is the same for FPC and Delphi.

    • Note that with FPC, you have access to our Android services and iOS services. They now implement in-app purchases, ads, analytics, local notifications, Google Play Games / Apple Game Center and more integrations. They could and will implement more (including the camera, location etc.), so we can have feature parity with FireMonkey too.

    • With Delphi, our Android services and iOS services are not available. Instead, rely on FireMonkey functionality, e.g. FMX supports in-app purchases.

We hope you enjoy this new support!

If you enjoy using our engine, please support us on Patreon. Other ways to donate are also welcome. We need your support to dedicate time to develop cool new features like this one 🙂 Have fun making games!

Comments on the forum ➤