Build Tool

Michalis Kamburelis edited this page Feb 2, 2018 · 45 revisions

Together with the engine we include a tool "castle-engine" to help with building and packaging your programs for various platforms (standalone, mobile, web browser...).

Quick installation instructions

  1. Download Castle Game Engine

  2. Compile castle-engine tool:

    • By command-line: just execute the script castle_game_engine/tools/build-tool/
    • Alternatively, by Lazarus:
      1. Open in Lazarus the package castle_game_engine/packages/castle_base.lpk and press "Compile" button in the package window.
      2. Then open in Lazarus the project castle_game_engine/tools/castle-engine.lpi and use "Compile" command (in the "Run" menu).
  3. Make castle-engine binary available on environment variable $PATH. The goal is to be able to execute castle-engine from command-line comfortably. Either extend your $PATH to include ..../castle_game_engine/tools/build-tool/ directory, or move the castle-engine[.exe] to some directory that is already part of your $PATH.

  4. To compile projects using the build tool, it must also be able to find the engine (either in source or compiled form):

    • One way to achieve this (advised) is to define an environment variable $CASTLE_ENGINE_PATH to indicate a directory that contains castle_game_engine or castle-engine directory (with engine sources). This way sources of our engine will be automatically used (and recompiled when necessary, which is also cool for developing engine modifications).

      For example, on Unix, you could put this in your ~/.bashrc file:

      export CASTLE_ENGINE_PATH=$HOME/sources/castle_game_engine/

      On Windows, you can define environment variable in the "Advanced" section of the system properties in the control panel. Google to find an exact instructions for your Windows version, if unsure.

    • Alternative is to specify within your FPC configuration file (fpc.cfg, see here if you don't know where to find it) the directory where you store the compiled units of our engine (*.ppu, *.o files). Specify them in fpc.cfg using the -Fu option. This assumes that you compiled the engine earlier, e.g. using "make" in castle_game_engine (or because the compiled engine units are already installed by the Debian package).

Quick usage instructions

Open a terminal (command-line), and enter the directory containing CastleEngineManifest.xml file. This is the main project directory.

Run this command to compile the project (for the current operating system and processor):

castle-engine compile

Run this to compile and also package (again, for the current operating system and processor):

castle-engine package

By default we compile in release mode. Use option --mode=debug to compile a debug version (slower, but more friendly for various debuggers).

That's it, you can now use our "build tool" to easily compile and package your games for various platforms:) Read on to learn about more useful commands of the build tool.

Creating and using the manifest file for your projects

Create a CastleEngineManifest.xml file in your project's directory. See the CastleEngineManifest.xml examples wiki page for samples and documentation. You can create an trivial starting CastleEngineManifest.xml file by executing castle-engine create-manifest. The manifest file describes your project's name, source code, what files to include in the package and such.

Then you call castle-engine from within your project's directory (or any subdirectory, we automatically look for CastleEngineManifest.xml in parent directories) to quickly compile, package and clean the project. See the description of command-line parameters to castle-engine below. The tool is integrated with our engine, so it can automatically compile the code correctly, and package it following our usual conventions. The data for the game is automatically packaged. On Windows the required DLL files are automatically included (see also the description of <dependencies> in CastleEngineManifest.xml). On Android the required Java wrappers and libraries are automatically used.

Special file/directory names:

  • The data subdirectory of the project, if found, is used for game data. It is automatically included in the game package for all platforms. It is accessible at runtime using ApplicationData('xxx.png') function, it returns URL pointing to the xxx.png file within data.

    We filter out some common development files like *.xcf and *.blend* from the data. See also <include> and <exclude> directives (in CastleEngineManifest.xml) to add/remove specific files from the package. These allow to add/remove files both inside and outside of data.

  • The data/material_properties.xml file, if found, is assumed to be used for material properties configuration. The subcommand castle-engine auto-generate-textures will use it to know which textures should be compressed and downscaled. At runtime, load this file to MaterialProperties.URL to actually use the compressed and downscaled versions.

Note that using the build tool is optional. The Castle Game Engine is just a set of Object Pascal units. You can use them in your programs, and compile/package the final program/library however you like. You can directly use Lazarus or command-line FPC to compile your game, and it's a sufficient approach when you develop a standalone game --- since the compiler generates a working executable that you simply run. And you can distribute it however you like.

However, using the build tool is nice to automate some tasks. For example, in case of Android and iOS, "building and packaging" is not a trivial process --- after compiling there are some steps you have to follow to get a final package that you can distribute to install/run your program. The build tool does it for you automatically, for example it can create fully-working Android apk, you only provide your Pascal source code.

Main advantages of using the build tool:

  • It can trivially easy package your game for Android. Once your code compiles for Android, packaging it to a production-ready xxx.apk file (that you can distribute freely, e.g. upload on Google Play) is trivial, just call "castle-engine package --os=android --cpu=arm". It can also package to a debuggable apk, that can be inspected with debuggers based on "gdb".
  • It can trivially easy package your game for iOS. Just call "castle-engine package --target=ios", and then open the created project in XCode (to run it in simulator, publish...).
  • It also takes care of resources (with icon, version information, manifest) on Windows.
  • It can also compile and package your game for desktop operating systems like Linux and Windows. This is comfortable, making sure that the same compilation options and the same packaging rules (what to include / what to exclude) are used when packaging your game for all targets.

Commands supported by the castle-engine tool


Create CastleEngineManifest.xml file if it does not exist yet, guessing the project name based on directory name. You can use this CastleEngineManifest.xml as a starting point.


Compile the project, with the syntax options and optimizations suggested for programs using our engine. Remember that this is not the only possible way to compile programs using our engine (for example, many people just compile using Lazarus, which is very fine if you simply create desktop games).

By default we compile for your current OS (operating system) and processor, so if you're on 32-bit Windows -> you will compile a 32-bit Windows binary, if you're on 64-bit Linux -> you will compile a 64-bit Linux binary and so on. You can use --os and/or --cpu options to cross-compile. Underneath, proper cross-compilation options will be passed to FPC.

For example:

  • Call castle-engine compile --cpu=x86_64 to compile a 64-bit version for the current operating system.
  • Call castle-engine compile --os=linux --cpu=x86_64 to compile a 64-bit version for Linux.
  • Windows is a little weird (due to historical conventions beyond FPC), and you have to use castle-engine compile --os=win64 --cpu=x86_64 (thus, you request 64-bit "twice" in the command-line) to get a 64-bit version on Windows. Use castle-engine compile --os=win32 --cpu=i386 to get a 32-bit executable for Windows.

Instead of --os and/or --cpu options, you can also use --target. A target is a collection of OS and CPU combinations that typically are distributed together. Right now, these targets are available:

  1. ios, which consists of 4 combinations of OS/CPU (see iOS to learn more). Specify it like --target=ios. Note that this feature is only available in CGE >= 6.2.0. Use the engine code from GitHub to test it now! :)
  2. custom (the default target), which means that we look at --os and/or --cpu options, and compile for this single OS/CPU.

Use --mode=debug or --mode=release or --mode=valgrind for a specific compilation mode. By default, it is "release". The "valgrind" mode is for profiling (speed, memory usage) using the excellent Valgrind tool.

In all cases, your programs will be compiled with the same FPC options as engine units, which means that we suggest ObjFpc syntax mode, and we turn the same optimizations as for the engine core.

You can customize what options we pass to FPC by:

  1. Adding options to the <custom_options> in CastleEngineManifest.xml. This is the good place to define options specific to your project (that should be used by all developers working with this project).

  2. Using --compiler-option command-line option. For example, --compiler-option=-dMY_DEFINE or --compiler-option=-gl --compiler-option=-gh. This is the good place to pass options specific to your development system or preferences, that should not be shared by all developers working on this project.

Use --plugin to compile a web browser plugin.

Use --output DIR to place the output files (executable, temporary castle-engine-output subdirectory) in a specified directory. When not given, they are placed in the current project directory. This option is also available for other commands, like package, install and run. This is available only since Castle Game Engine >= 6.5.


Create an installable package with your application.

Alternatively, on some platforms (iOS), this instead creates "something as close to the installable package as possible", which in case of iOS means that it creates an XCode project.

Use --cpu, --os or --target options to specify target operating system/processor (by default, we package for current standalone platform).

  • For the standalone platforms, right now we package to a simple zip / tar.gz archive containing the executable, libraries and data.
  • For the Android (when --os=android --cpu=arm), we create a complete apk with your application, ready to be installed and uploaded to Google Play!
  • For iOS (when --target=ios), we create an XCode project, that you can run and publish using XCode.

Note that the "packing" sometimes requires that the build tool can find it's data directory (for external libraries, for Android project templates and so on). If you have the engine sources, the easiest way is to define environment variable $CASTLE_ENGINE_PATH to indicate a directory that contains castle_game_engine or castle-engine. Otherwise make sure that the build tool "data" is installed correctly --- on Windows is should be alongside the castle-engine.exe file, on Unix is can be in system-wide location /usr/local/share/castle-engine or /usr/share/castle-engine .

You can use --mode=xxx option when packaging, just like when compiling. Use --mode=debug or --mode=release for a specific compilation mode. By default, it is "release". You can use --mode=debug to package a debug release, which may be useful to distribute to users interested in beta-testing.

In some cases, the --mode also affects the packaging wrapper. For example, on Android, a debug apk is marked as "debuggable" (using ndk-gdb). Also, only a debug apk may use a debug signing key (our build tool will automatically fallback from release apk to debug apk if you did not provide a release key in AndroidSigningProperties.txt).

To make sure that we recompile everything in the current mode (e.g. a release mode), this does clean, and then compile, and only then actually packages the result. You can change this behavior:

  • Use --fast to avoid cleaning at the beginning. In effect, we will recompile only what changed. This is usually much faster, and suitable for the development, if you call the package command often (e.g. because you're testing on an actual Android or iOS device). This is especially useful on iOS, when the full compilation takes a while (since it must compile for 4 platforms).

    For the final release builds, it's more reliable to not use this option. This makes sure that we recompile 100% of your code in proper (e.g. release) mode, with proper options and such.

  • Use --assume-compiled to say that you already compiled the application in proper mode before calling the package action. We will not do clean and compile in this case at all. This is obviously much faster, but you need to make sure to call compile beforehand yourself.


Install the application created by previous "package" call.

Use --os, --cpu or --target options to specify target operating system/processor (by default, we install for current standalone platform).

  • This is useful when OS is "android", it installs and runs the apk package created by previous "package" call for Android. Useful for quick testing of your app on a device connected through USB. Note: it's best to first test do you see your device using SDK tools, for example execute adb devices and see is your device listed.

  • Use --plugin to install a web browser plugin. We install the compiled plugin such that it should be visible by all web browsers supporting NPAPI. (On Windows, this means installing proper registry entries. On Unix, it means copying the library to special directory.)


Run the application.

As usual, use --os, --cpu or --target options to specify target operating system/processor (by default, we run the normal (exe) application on a current standalone platform).

On some platforms, it requires packaging and installing the application first. This applies to Android: we install and run on a device connected through USB. Use the "package" and "install" commands before this.

On other platforms (e.g. standalone Windows, Linux, Mac OS X...), this simply runs the last compiled application. So just "compile" the application first.

For example, on Android you can package and install and run your application like this:

castle-engine package --os=android --cpu=arm
castle-engine install --os=android --cpu=arm
castle-engine run --os=android --cpu=arm

You can specify parameters to pass to the application after the special "--" parameter. For example,

castle-engine run -- --debug-log

This will run your application with command-line parameters --debug-log. In your application, you can read them with the help of CastleParameters unit. The parameters are only supported by the command-line applications, they are ignored in other environments (e.g. there's no way to pass them to an Android application).


Package source code, which means just to package whole project directory (cleaned up first).

It creates xxx-VERSION-src.tar.gz archive, with VERSION obtained following the <version> element in the CastleEngineManifest.xml.


Clean compilation and packaging temporary stuff. This does not remove final packaging files.


Compile the Object Pascal file (unit/program/library) given as a parameter. This does not search for the Castle Game Engine project's manifest in the CastleEngineManifest.xml file. It merely calls "fpc" with proper command-line options for units/programs/libraries using our engine.

Use this instead of "compile" only if there's some good reason you don't want to use CastleEngineManifest.xml to manage your project.


Create GPU-compressed versions of textures, and downscaled textures, for the textures mentioned in <auto_generated_textures> inside the file data/material_properties.xml. Such GPU-compressed and downscaled textures can then be automatically used in your application. See for instructions how to use it and example data/material_properties.xml.

If the output textures are already created, they are updated only if the output timestamp is earlier than input. This usually allows to automatically do only the necessary work, similar to how Makefiles operate. To force recreating all textures, just call "auto-generate-clean" first.


Clear "auto_generated" subdirectories. They should contain only the output created by "auto-generate-textures" target. In the future, it is possible that more things will be placed there (for example, modern GPUs allow mesh data compression).


Generate standalone (desktop) program code in the file xxx_standalone.lpr. It uses the game_units defined in the CastleEngineManifest.xml to determine the correct uses clause of the program file.

You can use this program code to compile the project using any tool you want, not necessarily our build tool. E.g. maybe you like using fpmake. You can also customize this project file, and then use it as a standalone_source in the CastleEngineManifest.xml.

Also generates Lazarus project information in the file xxx_standalone.lpi. Together with xxx_standalone.lpr, this allows you to open this project in Lazarus to edit, compile, debug and run it from Lazarus. You can also compile it using lazbuild.

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.