-
Fink.
macOS
Table of Contents
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 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.
|
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 GUI tools (view3dscene, castle-view-image) 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.
|
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.
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)
- 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. 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/datasubdirectory. This way user can move aroundMyApplication.appto 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/datasubdirectory is not found, we will use thedatasubdirectory that is sibling toMyApplication.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.appdirectory), use the menu item "Run → Package → macOS App Bundle (APP)", or on command-linecastle-engine package --package-format=mac-app-bundle. -
Alternative often used distribution method on macOS is a
.dmgfile. It’s just a disk image that can contain anything, likeMyApplication.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 toBundlePath, likeBundlePath + '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.