1. Installation of FPC and Lazarus

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 favorite package manager like
- Homebrew - see FPC in Homebrew, Lazarus in Homebrew,
- MacPorts,
- Fink.
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.

Note	The FPC compiler needs the XCode command-line developer tools installed. To do this, open terminal (/Applications/Utilities/Terminal) and execute `xcode-select --install`.

More information:

2. Installation of Castle Game Engine

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.

Warning

Editor (castle-editor) and other tools (castle-engine, castle-model-viewer, castle-image-viewer) are unsigned applications for macOS right now. Double-clicking them for the first time will result in an error along the lines "developer cannot be verified". You have to right-click on them, choose "Open" from the context menu, and then you will be able to confirm that you want to open an unsigned application.

So before using the engine please run all the binaries in bin subdirectory once, by right-clicking on them, and accept the warning that they are unsigned applications. Do this at least for castle-editor, castle-engine and castle-model-viewer to use the engine comfortably. Note that castle-engine is command-line, and running it like this will just print the help message — that’s fine, it’s just to make macOS remember that you trust this application.

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

3. Using TCastleWindow

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

By default, TCastleWindow on macOS uses Cocoa with AppKit library, coded using Objective-Pascal. This makes it a completely native application on macOS. See Cocoa backend (CASTLE_WINDOW_COCOA) overview for the features we support on macOS.

4. Using TCastleControl

Using TCastleControl on macOS is completely standard. Just drop TCastleControl on LCL form.

Note that TCastleWindow is more advised, as a standard way to create a window where Castle Game Engine can work.

5. Other libraries

OpenAL (sound): On macOS >= 10.4, OpenAL comes already preinstalled. So sound will work automatically.
VorbisFile (reading OggVorbis): It may be installed using MacPorts, Homebrew or Fink.
LibPng: If you want to use LibPng library in your programs, to read PNG faster, you can install it using MacPorts, Homebrew or Fink.

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.
FreeType (reading font files): It is available in package managers like Homebrew (install using brew install freetype). As a fallback we will also try to use FreeType version installed by your X11, in /usr/X11/lib/ .

6. macOS application bundles

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.

Note	You can disable using application bundle by setting `mac_app_bundle="false"` in the CastleEngineManifest.xml. Disabling it makes sense for command-line (not GUI) applications.

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.
If the 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.

7. macOS packaging to zip and dmg

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, like BundlePath + 'Contents/MacOS/libpng.dylib'.

See macOS Libraries on FPC wiki for general instructions how to include library inside a bundle.

8. FAQ

8.1. Apple says that OpenGL(ES) is deprecated. What happens if they remove OpenGL(ES) from macOS and iOS?

Short answer: We will integrate seamlessly with ANGLE, that has a complete OpenGL ES 3.0 support, on top of Metal API.

Full answer:

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 definitely have an alternative renderer:
- BGFX is right now attractive option for us.
  
  This in turn has various backends, including Metal, Vulkan, various OpenGL (ES) and Direct3D versions.
- Direct Vulkan renderer. Vulkan is 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 this page and create a pull request to cge-www repository.