To build applications using the engine, you must install Free Pascal Compiler (FPC). Most likely you also want to install Lazarus, a Pascal IDE.
Follow download links from the official Lazarus webpage to download Lazarus and FPC for macOS. You should download and install all 3 dmg files (Lazarus, FPC, FPC sources).
Alternatively (if you use a package manager like Homebrew): You can also install FPC and Lazarus using your favourite package manager like
Alternatively (advanced): You can also install FPC and Lazarus using fpcupdeluxe. While the UI may be a bit overwhelming, in the end you just hit big button "Install FPC + Lazarus" and it reliably installs the specified FPC + Lazarus version. And it allows to easily add cross-compilers.
The FPC compiler needs the XCode command-line developer tools installed. To do this, open terminal (/Applications/Utilities/Terminal) and execute
Just download the official binary release from Castle Game Engine main page. The editor and various tools are inside the
bin/ subdirectory. Just double-click the
castle-editor application to run it.
After installation visit the editor Preferences and make sure that FPC, Lazarus and Castle Game Engine locations are detected, or set them manually.
Due to Apple "translocation" mechanism (that internally executes the application from a random place on disk, if it was part of a zip downloaded from the Internet) you will likely have to set Castle Game Engine path in "Preferences" → "General". There will be a warning, guiding you to do it, on the initial editor form.
TCastleWindow on macOS is completely standard. Just run the application as usual, using "Compile And Run" menu item (key shortcut is
F9) from the editor. Alternatively, you can use
castle-engine run on the command-line.
When creating new project in CGE editor, it will use
TCastleWindow by default to display a window where the engine will render.
On macOS >= 10.4, OpenAL comes already preinstalled. So sound will work automatically.
Note that this is not necessary. If we don’t find LibPng, we will fallback to reading PNG using Vampyre Imaging Library, which works too.
It is available in package managers like Homebrew. As a fallback we will also try to use FreeType version installed by your X11, in
To run a GUI application on macOS we use macOS application bundles. The application bundle is actually just a directory with name like
MyApplication.app and some standard organization for executable, icons, data.
When running the application during development we create a temporary application bundle, using symlinks to actual files (so it will be created lighting fast, even if you have large game data, as we will not copy data — only symlink to it). This applies to running application from CGE editor, or when using
castle-engine run on the command-line.
When packaging the application we also create an application bundle, this time by really copying the files/dirs into proper places. This gives you
MyApplication.app that is ready to be distributed to users. This applies when packaging from CGE editor, or when using
castle-engine package from the command-line. You can also request the application bundle format explicitly, using CGE editor menu item "Run → Package → macOS App Bundle (APP) zip", or on command-line
castle-engine package --package-format=mac-app-bundle-zip.
You can disable using application bundle by setting
Behavior of the data directory (
castle-data: protocol) on macOS, if the application detects it is being run through the "application bundle":
We expect the data to be found inside
MyApplication.app/Contents/Resources/data subdirectory. This way user can move around
MyApplication.app to move, install and uninstall the application.
When creating application bundle, we (CGE editor and CGE build tool) make sure to make project data actually present there, so things should Just Work and you don’t need to do anything.
MyApplication.app/Contents/Resources/data subdirectory is not found, we will use the
data subdirectory that is sibling to
MyApplication.app. This feature is intended to be used only during development with Lazarus. This way things work "out of the box" if you run through Lazarus, with checkbox “Use Application Bundle for running and debugging” in Lazarus project options.
By default we put the application bundle in a zip file. If you only want the bundle (
MyApplication.app directory), use the menu item "Run → Package → macOS App Bundle (APP)", or on command-line
castle-engine package --package-format=mac-app-bundle.
Alternative often used distribution method on macOS is a
.dmg file. It’s just a disk image that can contain anything, like
MyApplication.app. See Building Fancy DMG Images on macOS for nice description how to make the directories inside dmg look pretty, so you can visually suggest user to drag your application in the Applications folder.
There are convincing arguments that using ZIP is actually more user-friendly than DMG (users can just double-click to unpack, and they have the application; they don’t need to understand how "disk image" works). See also here for discussion. And making zip is definitely simpler. So that’s why we do ZIP, not DMG, by default now.
If you need, you can add additional dynamic libraries to the bundle. If you link to them dynamically (e.g. using our
TDynLib.Load), you should load them from a path relative to
BundlePath + 'Contents/MacOS/libpng.dylib'.
See macOS Libraries on FPC wiki for general instructions how to include library inside a bundle.
To improve this documentation just edit the source of this page in AsciiDoctor (simple wiki-like syntax) and create a pull request to Castle Game Engine WWW (cge-www) repository.
Copyright Michalis Kamburelis and Castle Game Engine Contributors.