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 download 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 regularly provide binaries (like FreeBSD or macOS). 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 showing the process of CGE compilation (a subset of this guide) on Linux.

Looking for a one-liner that does everything? You can execute pack_release.sh script (this is used to create actual releases on all platforms). But beware that it requires a few preexisting tools on PATH. Most people that want to compile our engine "just to peek a bit under the hood" will have easier time following the steps below than by trying to just execute pack_release.sh and debugging all its requirements.

2. Install FPC and Lazarus

• It is easiest to install Lazarus bundled with FPC.
• You can also get both Lazarus and FPC from fpcupdeluxe.

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 https://github.com/castle-engine/castle-engine/

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 https://github.com/castle-engine/castle-engine/

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/ # first enter the build tool directory
  ./castle-engine_compile.sh
  

• Alternatively: If you're on Windows and familiar with PowerShell command-line, then it is simplest to do this in PowerShell:

  cd castle-engine/tools/build-tool/ # first enter the build tool directory
  Set-ExecutionPolicy Bypass -Scope Process
  ./castle-engine_compile.ps1
  

  Note: The Set-ExecutionPolicy... is to avoid errors because our PowerShell script is not signed. Without it, you will likely get an error like The file ....\castle-engine_compile.ps1 is not digitally signed. You cannot run this script on the current system. We follow advise to solve it e.g. from Chocolatey.

• Alternatively: If you're not friendly with command-line, compile by Lazarus:

  1. Open in Lazarus this package from CGE repository: packages/castle_base.lpk .

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

Next, place build tool exe in proper directory, so that it can be found by other CGE tools, and so that it will detect CGE:

• Advised: 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 TCastleControl working. As editor uses TCastleControl, this is a necessary step when building editor yourself.

2. Open and compile (no need to install) in Lazarus castle_editor_components.lpk package.

   This package contains some units and registers some components that are only useful for CGE editor development. In particular, mbColorLib (LCL components to display nice color dialogs) and some forms for CGE property editors (in tools/castle-editor/components).

   Only install this package if you want to contribute to CGE development and edit all property editor forms.

   General users should not need to install this package. If you just want to build CGE editor, it is enough that Lazarus "knows" about this package, so just "Compile" this package and it will be linked with CGE editor. If unsure, and you later want to contribute (thank you!), you can install it later :) Remember that you should not use castle_editor_components.lpk in your own applications — the units and components in this package are internal for CGE development, we may change their API disregarding backward compatibility.

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

4. 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:

• (32-bit) castle-engine/tools/build-tool/data/external_libraries/i386-win32/ or
• (64-bit) castle-engine/tools/build-tool/data/external_libraries/x86_64-win64/ .

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. GTK 2 (we plan to switch to GTK 3, and editor may switch to Qt5)
3. LibPng (to open png files more efficiently)
4. ZLib (to unpack gzip files; also used by LibPng)
5. OpenAL (to play sound)
6. FreeType (to load font files)
7. 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 and derivatives (like Ubuntu or Raspberry Pi OS), this command should install everything you need:

  sudo apt install libgtk2.0-dev libglx-dev libgl-dev libqt5pas-dev libpng-dev libz1 libopenal1 libfreetype6 libvorbisfile3

  (Anything missing? Search)

• On Fedora, this command should install everything you need (and more, some of these are FPC requirements actually, not CGE):

  sudo dnf install gtk2 gtk2-devel libX11-devel make binutils glibc-devel mesa-libGL-devel qt5pas

  (Anything missing? Search)

• On Arch Linux and derivatives, try this:

  sudo pacman -S gtk2

Note that we link to most libraries dynamically using "dlopen" Unix mechanism. So it is not necessary to install e.g. libfreetype6-dev. And instead of libpng-dev you can install any recent libpngXY with XY indicating version 1.2-1.6 (various distros have a bit different naming here).

6.3. macOS

macOS requirements are listed here.

7. (Optional) Compile castle-model-viewer

To have fully-working installation, build also castle-model-viewer. 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 https://github.com/castle-engine/castle-model-viewer/

You now have a number of equivalent options to compile:

• Use Lazarus.

  1. First, Lazarus must be aware of the castle_window package. It is best to use Register Lazarus Packages button from the CGE editor, as described in the Installation manual. Or you could just open the packages/castle_window.lpk package in CGE sources, and "Compile" it from Lazarus.

  2. Then open in Lazarus castle_model_viewer.lpi, and use "Run -> Compile" menu item in Lazarus.

• Or run castle-editor. Open the project in castle-model-viewer/CastleEngineManifest.xml, and use "Compile" from CGE editor.

• Or use this in terminal (if you put the build tool on $PATH):

  cd castle-model-viewer/
  castle-engine compile
  

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

8. (Optional) Compile castle-image-viewer

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

Get the code from GitHub:

git clone https://github.com/castle-engine/castle-image-viewer/

Similar to castle-model-viewer step above, you now have a number of equivalent options to compile:

• Use Lazarus.

  1. First, Lazarus must be aware of the castle_window package. It is best to use Register Lazarus Packages button from the CGE editor, as described in the Installation manual. Or you could just open the packages/castle_window.lpk package in CGE sources, and "Compile" it from Lazarus.

  2. Then open in Lazarus castle_image_viewer.lpi, and use "Run -> Compile" menu item in Lazarus.

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

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

  cd castle-image-viewer/
  castle-engine compile
  

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

9. (Optional) Compile pasls (Pascal LSP)

If you use pasls (Pascal LSP), for example with our Visual Studio Code extension, then download and build it too. Like this:

git clone https://github.com/castle-engine/pascal-language-server.git
cd pascal-language-server/
git submodule update --init --recursive
cd server/
lazbuild pasls.lpi

Then put the pasls binary in the castle-engine/bin/ directory. This is where it's expected e.g. by our Visual Studio Code extension.

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

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

   If you're on Unix (like Linux), or use Cygwin under Windows, then you can just execute make. It recompiles all the tools, all Lazarus packages, and the editor, and places the binaries in bin/.