Delphi | Manual | Castle Game Engine

Delphi

Table of Contents

1. Introduction
2. Configure Castle Game Engine to use Delphi
3. Presentations
4. Platforms supported with Delphi
5. Delphi versions supported
6. C++ Builder
- 6.1. Redistributing C++ Builder applications by default requires redistribution of Delphi run-time BPLs too

1. Introduction

We support Delphi, a powerful commercial Pascal IDE and compiler.

Any Delphi tier, including free Delphi Community Edition, is fine.

We are an official Embarcadero Technology Partner. This means that engine developers have full access to the latest Delphi version, with all the Delphi platforms (including Android and iOS), for free. For testing CGE compatibility.

If you like Delphi compatibility, and want to see more of it (e.g. more platforms or Delphi-specific integration tools), please voice your needs and if you can — support us on Patreon!

2. Configure Castle Game Engine to use Delphi

In Castle Game Engine editor, open "Preferences" dialog. In both the "Code Editor" and "Compilation" tabs set "Delphi", if it was not auto-detected already.

That’s it. CGE editor is now integrated with Delphi. You can test it:

Press F9 to compile the project from CGE editor (using CGE build tool which will use Delphi command-line compiler under the hood).

Note
In case of Delphi Community Edition: It doesn’t have command-line compiler, so you have to compile the project using F9 from the Delphi IDE.
Double-click on Pascal files to open them in Delphi.
Use "Code → Open Project in Code Editor" menu item to open project in Delphi.

3. Presentations

4. Platforms supported with Delphi

We support now Windows (both 32-bit and 64-bit) and Linux. This means that you can compile and run your CGE applications on these platforms using Delphi. See Linux for Linux-specific setup notes.
Other platforms will come, next one is most likely Android.
You can use TCastleWindow, which is our standard way to create CGE window. Our "New Project" templates as well as most examples use it.
You can alternatively use TCastleControl that allows to put CGE rendering on FMX (FireMonkey) or VCL form. See here for details.

To register the TCastleControl component in Delphi IDE, follow Delphi packages installation instructions.

5. Delphi versions supported

The engine is tested and supported on all Delphi versions >= 10.2.1. It was actively tested on 10.2, 10.3, 10.4 (including CE), and all Delphi 11 editions (including 11.3 CE).
The exact Delphi version support from Castle Game Engine depends on the target platform, since the support for non-Windows platforms isn’t always perfect in older Delphis:

Windows (32-bit and 64-bit)

Delphi >= 10.2.1

Linux (64-bit only)

Delphi >= 11.3

Android, iOS, macOS (Upcoming)

Delphi >= 10.4 (see below for reasons; these requirements may change once we finalize these platforms)

We will not support Delphi versions older than 10.4 for mobile (Android and iOS).

Reason: The older Delphi versions have crazy compatibility-breaking change to String handling on mobile: strings are 0-based (but only on mobile!, on desktop they remained 1-based) and Embarcadero/Idera recommended way forward was to use TStringHelper, with all operations 0-based, and maybe treat strings as immutable.

This is documented now in Zero-based strings (Delphi). In the past page Migrating Delphi Code to Mobile from Desktop (for Delphi XE7) had a longer section "Use 0-Based Strings".

Adjusting to this would mean rewriting all String handling code in the engine to use new TStringHelper. And it would be quite risky task — as the global String routines remained available for mobile, but they were nearly useless for cross-platform code, as they would use 1-based on desktop and 0-based on mobile. Thus causing hard-to-find bugs, as the same code would compile everywhere, but would work differently between desktop and mobile.

We’re happy that Embarcadero backed off from this weird decision in later Delphi versions. See Delphi 10.4 (Sydney): Zero-based strings (Delphi). In particular it says "In general terms, string indexing is now uniform across platforms and uses 1-based index model." and "Default" is "`{$ZEROBASEDSTRINGS OFF}` for Delphi desktop and mobile compilers".

6. C++ Builder

The engine is fully compatible with C++ Builder. The complete engine class API is available from C++ in a natural way. You can use TCastleWindow or TCastleControl from C++, just like from Pascal. See the details in this article.

There are 2 examples in CGE specifically for C++ Builder, using engine API from C++:

examples/delphi/cpp_builder/fmx shows using TCastleControl inside FMX form.
examples/delphi/cpp_builder/window shows using TCastleWindow, with views, loading a design, operating on TCastleScene and more. It faithfully recreates in C++ the CGE Pascal example from the ITDevCon 2023 conference.

Note	For C++ Builder you need to Build the packages for all your target platforms, which means: both Win32 and Win64. This is in contrast to usage from Pascal, where it is enough to only Install them for Win32 (Delphi IDE architecture).

The C++ Builder compatibility is available for C++ Builder versions 11.3 and up.

6.1. Redistributing C++ Builder applications by default requires redistribution of Delphi run-time BPLs too

C++ Builder applications by default require redistribution of Delphi run-time libraries (BPL files) too. This is unrelated to CGE. So you cannot just give your users the resulting EXE file, you need to also provide all the BPL (run-time packages) it uses. If you use CGE, then in addition to RTL and FMX, you will also need to redistribute CGE run-time packages (BPL files).

If you forget to distribute the BPL files along with your EXE, users will see an error message like this:

If you want to avoid it, and have everything contained in one big EXE file, follow this answer; How do I create a stand-alone application in C++Builder for a solution. In short (as of RAD Studio 12.0) uncheck in project options

"Building → C++ Linker → Link with Dynamic RTL" and
"Packages > Runtime Packages → Link with runtime packages".

Applications are then compiled into a larger EXE, that is "stand-alone" and does not require BPL files to be distributed.

We have tested the above solution, it works for simple FMX applications and CGE applications using TCastleControl like examples/delphi/cpp_builder/fmx. Below is a screenshot, as you can see in the background we only transferred the EXE file to another computer and the data subdirectory.

Warning

Unfortunately examples/delphi/cpp_builder/window with these settings (no run-time packages) makes C++ Builder compiler crash with Access Violation. We haven’t tested whether this problem affects all C++ Builder applications using TCastleWindow, the reason behind it also unknown — TCastleWindow isn’t anything special, it just uses WinAPI (on Windows) under the hood to create a window with OpenGL context.

To improve this documentation just edit this page and create a pull request to cge-www repository.