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.
Short answer: We will integrate seamlessly with ANGLE, that has a complete OpenGL ES 3.0 support, on top of Metal API.
First of all, I (Michalis) hope that Apple will not go with the removal of OpenGL(ES) from their devices. Or that they will add Vulkan support as a 1st-class citizen on Apple devices, in exchange. I hope they will not make Metal the only API to access GPU on macOS / iOS.
Reason: Open technologies, including cross-platform open standards (like OpenGL and Vulkan), are what allows us to innovate and ultimately enjoy technology. The world seems to agree — as it stands, all platforms supported by CGE have OpenGL or OpenGLES support, and many have Vulkan support. Unless your software is only for Apple devices, it’s hard to be enthusiastic for Metal, an Apple-specific technology that ultimately solves a similar problem that Vulkan does on all other platforms.
As of now, OpenGL is still fully supported on latest macOS (including on Apple Silicon architecture) and OpenGLES is still fully supported on iOS (iPhone, iPad).
If however Apple will really remove OpenGL(ES) from future devices, and make Metal the only officially supported API for GPU access, we have a number of options. And we will be in a good company, a lot of projects will be in a similar spot — including Apple’s own Safari web browser that in the end has to support WebGL (an API much like OpenGLES, but available for web page developers from JS) translating it in an efficient way to something available on Apple devices.
Our first course of action will be using ANGLE that allows to effectively use OpenGLES API (and GLSL shaders) from CGE, and have them translated to Metal under the hood.
It’s efficient, it’s complete: full OpenGL ES 3.0 support.
It’s been in development for a long time, is supported by some big companies, it has multiple backends (not just Metal).
Apple itself contributes to it (see notes from MetalANGLE, fork where initial work has happened to support OpenGLES 2.0 and 90% of OpenGL ES 3.0 on top of Metal).
In the future, CGE will likely have an alternative Vulkan renderer. A new API, harder to use, more low-level, but with possibilities to deliver amazing performance and also scale better to multiple cores.
At that point, using MoltenVK will become an option to. It exposes Vulkan API and uses Metal underneath.
Finally, there is an option of developing another renderer in CGE on top of Metal.
We know we will have extensible architecture in CGE for multiple renderers. I have been playing with idea to implement a Vulkan renderer (see new_renderer_skeleton) and, beoynd some initial fun, of course it will imply the need for a pluggable architecture to implement many possible renderers. OpenGL(ES) will remain one, Vulkan will most likely become another, and it is possible that Metal will become yet another one.
However, please note — this (Metal renderer in CGE) is not an option that will happen fast. Making a new renderer "production-ready" (that is, making it more feature-packed / efficient than just using abstraction layer like Angle + existing OpenGLES renderer) is a lot of work. Moreover, CGE is a cross-platform game engine, and it’s hard to prioritize big work on something that only benefits Apple platforms. That being said, I would be very happy to see a dedicated contributor interested in adding Metal support. Or if you want to find and sponsor such contributor, that can be arranged (talk with us).
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.