Build Tool

Michalis Kamburelis edited this page Oct 6, 2016 · 30 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 option, 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 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.

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.

Use --plugin to compile a web browser plugin.

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.


Do "clean", then "compile" (unless --assume-compiled present), then create an installable package with your application.

Use --cpu and --os 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!

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


Install the application created by previous "package" call.

Use --cpu and --os 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 --cpu and --os 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).