Installing Cocos2d-x (macOS)

• Install Xcode
• Install Cocos2d-x 4.0
• Create a new Cocos2d-x project
• Compile and run for iOS
• Compile and run for macOS

As I mentioned in the previous post, I am going to use Cocos2d-x for my game engine. I will install it and make sure it works under different operating systems (macOS, Windows, Linux) and also compiles for different platforms (minus the Android).

In this post I will go through the steps I took to install it on my Macbook Pro!

Install Xcode

First, install Xcode, the native IDE for programming for macOS and iOS.

• Download and install Xcode from the App Store. It is the Apple’s free programming IDE and compiler.
• Now in a new terminal install the Xcode command line tools. The command line tools are not directly necessary to make and compile a Cocos2d-x projects, but it will come handy later in different occasions which you will see later.

xcode-select --install

At this point you can already compile for iOS devices. However to be able to compile for Android devices, You need to install some extra Android related stuff. It includes Apache Ant and Android Studio (and the packages that come with it: Android SDK and Android NDK).

Install Cocos2d-x 4.0

Now that Xcode is installed, it is time to install Cocos2d-x itself:

• Installing Cocos2d-x needs Python 2.7x installed which comes natively on macOS. Check your python version in terminal to see if you have the right version. Mine is 2.7.16.

python --version

• Download Cocos2d-x (cocos2d-x-4.0.zip) from www.cocos2d-x.org and unzip it in a folder that you want it to reside e.g. /Applications/Dev/
• Setup Cocos2d-x by running the setup.py in a terminal from inside of the unzipped folder e.g. /Applications/Dev/cocos2d-x-4.0/

python setup.py

• It sets up some environment variables first as below and then asks for some paths.
  • COCOS_CONSOLE_ROOT
  • COCOS_X_ROOT
  • COCOS_TEMPLATES_ROOT
• If you have Android Studio and Apache Ant installed in your system (in my case they are installed in Dev folder):
  • For NDK_ROOT question, put /Users/rezagn/Library/Android/sdk/ndk-bundle
  • For ANDROID_SDK_ROOT question, put /Users/rezagn/Library/Android/sdk
  • For ANT_ROOT question, put /Applications/Dev/apache-ant-1.10.7/bin

After going through the steps I mentioned above, I have these lines added to my ~/.profile settings file:

# Add environment variable COCOS_CONSOLE_ROOT for cocos2d-x 
export COCOS_CONSOLE_ROOT=/Applications/Dev/cocos2d-x-4.0/tools/cocos2d-console/bin
export PATH=$COCOS_CONSOLE_ROOT:$PATH 

# Add environment variable COCOS_X_ROOT for cocos2d-x 
export COCOS_X_ROOT="/Applications/Dev" 
export PATH=$COCOS_X_ROOT:$PATH 

# Add environment variable COCOS_TEMPLATES_ROOT for cocos2d-x 
export COCOS_TEMPLATES_ROOT=/Applications/Dev/cocos2d-x-4.0/templates
export PATH=$COCOS_TEMPLATES_ROOT:$PATH

# Add environment variable NDK_ROOT for cocos2d-x
export NDK_ROOT="/Users/rezagn/Library/Android/sdk/ndk-bundle"
export PATH=$NDK_ROOT:$PATH

# Add environment variable ANDROID_SDK_ROOT for cocos2d-x
export ANDROID_SDK_ROOT="/Users/rezagn/Library/Android/sdk"
export PATH=$ANDROID_SDK_ROOT:$PATH
export PATH=$ANDROID_SDK_ROOT/tools:$ANDROID_SDK_ROOT/platform-tools:$PATH

# Add environment variable ANT_ROOT for cocos2d-x
export ANT_ROOT="/Applications/Dev/apache-ant-1.10.7/bin"
export PATH=$ANT_ROOT:$PATH

If you don’t have these lines, add them to your setup file manually. Remember to replace my username “rezagn” with yours and make sure the paths are correct.

Create a new Cocos2d-x project

To make new projects, we will use the cocos command in the terminal. If you just type cocos and press Enter, you will get the command line options help.

~/Projects/games > cocos

/Applications/Dev/cocos2d-x-4.0/tools/cocos2d-console/bin/cocos.py 2.3 - cocos console: A command line tool for Cocos2d-x.

Available commands:
	run              Compiles, deploy and run project on the target.
	luacompile       Encrypt and/or compile lua files.
	deploy           Compile and deploy a project to a device/simulator.
	compile          Compile projects to binary.
	gen-simulator    Generate Cocos Simulator.
	new              Creates a new project.
	jscompile        Compile and/or compress js files.

Available arguments:
	-h, --help			Show this help information.
	-v, --version			Show the version of this command tool.
	--ol ['en', 'zh', 'zh_tr']	Specify the language of output messages.
	--agreement ['y', 'n']		Skip the agreement with specified value.

Example:
	cocos new --help
	cocos run --help

Create a new project by typing the full command as bellow. Feel free to change the folder as you wish.

cocos new install_test -p com.games.install_test -l cpp -d ~/Projects/

This will make a project called “install_test” with all the necessary files and sub folders of the Cocos2d-x project in your specified folder!

Since the new release of Cocos2d-x v4.0, CMake is used to create projects and compile under different platforms. That means that the Cocos2d-x projects won’t come with an Xcode project file like in the earlier versions. We need to make two different Xcode project files for our newly built Cocos2d-x project which we called “install_test”. One for macOS and one for iOS.

To create an Xcode project for macOS, run these commands in Terminal from inside the “install_test” project folder.

mkdir build_mac && cd build_mac
cmake .. -GXcode
open install_test.xcodeproj

To create an Xcode project for iOS, run these commands in Terminal from inside the “install_test” project folder.

mkdir build_ios && cd build_ios
cmake .. -GXcode -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphoneos
open install_test.xcodeproj

Compile and run for iOS

• Run Xcode.
• In Xcode open the project file from “ios-build” folder of the project.
• Select an iOS device from the top left. e.g. iPhone 11 Pro Max.

• From the menu go to Product->Run.
• Xcode should build the project with no problems and run it in a simulator window.

Compile and run for macOS

Considering that compiling and running for iOS needs the simulator, it might be easier and faster to do your test and development for macOS instead. To compile for macOS:

• Run Xcode.
• In Xcode open the project file from “proj.ios_mac” folder of the newly created test project.
• Select “test-desktop.app” and “My Mac” as target project and device.

• From menu go to Build->Run the same as you did for iOS and this should run the game.

Next