Build UPBGE on macOS

Install Xcode development tools

Download the latest version of Xcode from the Mac App Store for your system (it's free). Then, in Terminal run:

xcode-select --install

Install CMake & Subversion

Your macOS system needs 3rd party tools to configure your build environment. We recommend using Homebrew to install them. It's easy to install and instructions are on that site.

Once installed, run:

brew install svn
brew install --cask cmake

Get the sources

Note: If you are having troubles with the repository and submodules, just delete the folder and start fresh again.
Beware: Deleting a git folder will also remove any branch/work you made inside, act carefully.

mkdir ~/sources/
cd ~/sources/
git clone https://github.com/UPBGE/upbge.git
cd upbge
make update

Building

Note: There are two main ways to build UPBGE. You can use make or Xcode. Make is the easiest and fastest way but Xcode makes things like code signing and build options easier to manage.

With make:

To build with make, simply run this in Terminal:

cd ~/sources/upbge/
make

After the build finishes, you will find Blender.app ready to run in ~/sources/build_darwin/bin/

Note: By default, this will build with one thread. To speed up builds, use the -j flag followed by the number of threads to allow make to use. For 8 threads, the command would look like this: make -j8

With Xcode:

Make sure you've completed all the steps before the "building" section. If you want to build with Xcode, you first need to generate the appropriate Xcode project files with cmake. To generate the project, run this in Terminal:

cd ~/sources/upbge/
cmake . -B ../build_xcode/ -G "Xcode"

This will generate the CMake cache files and an Xcode project file in ~/sources/build_xcode/.

Now open Xcode and locate the Blender.xcodeproj file in ~/sources/build_xcode. This will initialize your UPBGE Xcode project in the editor. Now follow these steps to build your Xcode project:

1. Choose Automaticlly Create Schemes from the popup window.
2. In the upper center of the screen there should be a bar with some project information. Click the icon/button on the far left of this bar and select install from the dropdown.
3. Click the triangle run button to build the project. When the build is complete, you can run Blender.app from ~/sources/build_xcode/bin/. It will either be in a Debug, Release, or MinSizeRel folder. Normally it will be in Debug.

Note: If you see a popup window telling you the project uses custom architectures and asking you to update them, click Build. In newer Xcode versions, the software tries to create a universal binary but Blender has issues with building in this format.

Multiarch support

If you use an Apple Silicon M1 (arm64) powered computer, you will want to use the arm64 compiled UPBGE for your game development. However, your game will not run properly on Intel computers because Blenderplayer will be compiled for the Apple Silicon chip. To work around this, you will need the Intel (x86_64) version of UPBGE to open your game and export with.

UPBGE can be built for Intel (x86_64) based systems from the Apple Silicon (arm64) platform. To do this, open Finder and navigate to the "Applications" folder. In here, open "Utilities" folder and find Terminal. Duplicate the Terminal application and rename the duplicate to "x86 Terminal". Right click the application and select "Get Info" from the dropdown. In the popup window, select "Open using Rosetta" and close the window. Now run all the same steps in this guide using this application in place of the standard Terminal program. This will generate everything for the Intel platform and allow legacy CPUs to run them.

Note: Native arm64 binaries will run much faster on M1 Apple Silicon processors. Running x86_64 applications on these chips will be slower and is not recommended unless for compatibility reasons.

Code signing

Apple computers will refuse to run any software that hasn't been code signed. UPBGE has their own signing/authoring process for official builds but the code you generate with this guide will not be signed. It will work on your Mac and your Mac only. This also means that any games you export with your own builds will not work on anybody else's computers. You will need to enroll in the Apple Developer Program and sign in to Xcode with this account. You will then need to click the folder icon in the left Xcode panel and click "Blender". Click "Build Settings" > "All" and search for "Code Signing Identity". Switch this to your developer credentials. Users will most likely need to allow this program to run through System Preferences as Apple's "Gatekeeper" is an asshole to small time developers.

For any additional information about building Blender/UPBGE on macOS, visit the Blender Wiki page to learn more.