Compiling from source

1. Overview

The very latest Castle Game Engine version is always available as a source code from our Github repository.

Before compiling it yourself, make sure you really need to do this. After all, you can downlad the binary release of the engine that also contains the complete source code (it just also contains ready binaries for a particular platform). And the current binary releases (7.0-alpha.snapshot) contain the very latest features and fixes, quite like source code — as they are automatically rebuild after every commit. Oh, and if you're looking for win32 version, it is available on GitHub snapshot download page (we don't link it on the main CGE page because we advise win64).

That being said, there are of course valid reasons to compile engine yourself. E.g. if you want to contribute (create pull requests). Or if you want to test on desktop systems for which we don't provide ready binaries yet (like FreeBSD). Also, updating from source code is faster, as you'll only update from GIT what has changed.

So, read on :)

We also have a video version of this, showing the process on Linux.

2. Install FPC and Lazarus

We list the supported FPC and Lazarus versions here. We always support the latest stable release as well as a few older versions.

3. Get the CGE source code from GitHub

Get the source code of CGE from GitHub. In the terminal, do this:

git clone

You can make it a bit faster (if you don't care about getting historic revision and other branches than master) using this instead:

git clone --depth 1 --single-branch --branch master

4. Compile the build tool

Compile the command-line build tool.

  • If you're on Unix (like Linux) and familiar with command-line, then it is simplest to do this in the terminal:

    cd castle-engine/tools/build-tool/
  • Or you can compile by Lazarus:

    1. Open in Lazarus the package castle-engine/packages/castle_base.lpk and press "Compile" button in the package window.
    2. Then open in Lazarus the project castle-engine/tools/build-tool/castle-engine.lpi and use "Compile" command (in the "Run" menu).

Then create the subdirectory bin under the main CGE directory (so you'll have castle-engine/bin/) and move there the resulting binary castle-engine (castle-engine.exe on Windows).

Alternatively: You can add the castle-engine binary location to the environment variable PATH. On Unix, you can add something like export PATH="$PATH:$HOME/castle-engine/tools/build-tool/" to ~/.profile. On Windows, you can follow instructions here. If this step sounds complicated and unnecessary, just don't do it — putting the build tool into the castle-engine/bin/ is also good.

Alternatively: You can move the castle-engine binary to any place that is already on $PATH, e.g. on Unix to system-wide /usr/local/bin/. You should then also define environment variable CASTLE_ENGINE_PATH pointing to the CGE sources. On Unix, instead of using $CASTLE_ENGINE_PATH, you can also put the engine in system-wide /usr/src/castle-engine or /usr/local/src/castle-engine (or make it a symlink, like sudo ln -s $HOME/my/castle-engine /usr/local/src/castle-engine).

5. Compile the editor

  1. Install in Lazarus castle_components.lpk package following the documentation how to get TCastleControlBase working. As editor uses TCastleControlBase, this is a necessary step when building editor yourself.

  2. Open in Lazarus castle-engine/tools/castle-editor/castle-editor.lpi and use "Compile" command (in the "Run" menu).

  3. Just like with the build tool: move the resulting binary (castle-editor on Unix, castle-editor.exe on Windows) to the castle-engine/bin/.

6. Make sure you have the necessary libraries

6.1. Windows

On Windows, it is important to make sure that the dynamic libraries (xxx.dll files) are in the correct place, alongside the editor castle-editor.exe file.

The DLL files are in:

You need to copy all these DLL files to the castle-engine/bin/ directory, alongside the castle-editor.exe .

Alternatively you can modify your PATH environment variable to include the directory where the DLL files are. Remember to restart the appropriate programs, to make them use the new value of PATH.

Be sure to use the DLL files corresponding to your target platform. For example, if you use FPC/Lazarus for 32-bits, then you make executable for 32-bits (by default), and you should use DLLs for 32-bits. Even if you work on a 64-bit Windows.

6.2. Linux, FreeBSD

We use the following libraries:

  1. OpenGL (essential for the engine to work; used to render)
  2. LibPng (to open png files more efficiently)
  3. ZLib (to unpack gzip files; also used by LibPng)
  4. OpenAL (to play sound)
  5. FreeType (to load font files)
  6. VorbisFile (to load OggVorbis files)

Most of them are already present on all Unix desktop installations.

On your (developer) system, you will need the development versions of some of these libraries. This allows to build programs that link to these libraries. On Debian systems, this command should install everything you need:

sudo apt install libgtk2.0-dev libgl1-mesa-dev

Note that we link to many libraries dynamically using "dlopen" Unix mechanism. So it is not necessary to install e.g. libpng-dev or libfreetype6-dev.

6.3. macOS

macOS requirements are listed here. We know this is somewhat complicated — we want to make this more straightforward for mac users in the future.

7. (Optional) Compile view3dscene

To have fully-working installation, build also view3dscene. Editor executes it on double-click to view all our scene formats, 3D and 2D: glTF, X3D, Spine JSON, sprite sheets etc..

Get the code from GitHub:

git clone

You now have a number of equivalent options to compile:

  • Open in Lazarus view3dscene.lpi, and use "Compile" from Lazarus.

  • Run castle-editor, open project in view3dscene/CastleEngineManifest.xml, and use "Compile" from CGE editor.

  • Use in terminal (if you put the build tool on $PATH):

    cd view3dscene/
    castle-engine compile

Similarly to the previous tools, we advise to put the binary view3dscene (view3dscene.exe on Windows) inside the castle-engine/bin/ directory, alongside other tools.

8. (Optional) Compile castle-view-image

You can build also castle-view-image. Editor executes in on double-click to view 2D images.

Get the code from GitHub:

git clone

Similar to view3dscene step above, you now have a number of equivalent options to compile:

  • Open in Lazarus castle-view-image.lpi, and use "Compile" from Lazarus.

  • Run castle-editor, open project in castle-view-image/CastleEngineManifest.xml, and use "Compile" from CGE editor.

  • Use in terminal (if you put the build tool on $PATH):

    cd castle-view-image/
    castle-engine compile

Similarly to the previous tools, we advise to put the binary castle-view-image (castle-view-image.exe on Windows) inside the castle-engine/bin/ directory, alongside other tools.

9. Test!

You now have a complete working CGE installation, with the command-line build tool and GUI editor. Follow the manual to set it up and use as a normal user :)

10. Updating

To pull the latest changes

  1. Update from GIT as usual (git pull --rebase).

  2. Follow the above steps to recompile at least the build tool and editor.