Cocos2d-x is a multiplatform game framework. It is a reimplementation of Cocos2D for iPhone in C++.
The main idea about it is that you are going to write plain old C++ code and that code will run on both Android (via JNI thanks to the NDK) and iPhone. It also has support for Win32, WoPhone and some other platforms, check them out on the Cocos2D-X website.
The zip that you can download from the project’s website includes wizards/helpers for creating a new project for each of the supported platforms, but it doesn’t have a wizard that will let you specify what platforms do you want to work on and then generate everything from one shot.
I took some time and figured out a way to manually create one of these hybrid projects for Android and iOS. This article is actually based on an edited version of an older article of mine which addressed an older version of cocos2dx and mainly assumed that you were using Xcode 3.
- 1 Prerequisites
- 2 Creating the iPhone project
- 3 Creating the Android project
- 4 Merging the Android project into the iPhone project
This tutorial uses the cocos2d-1.0.1-x-0.11.0 release. I will try to keep the guide updated as new versions are launched, but I could really use your help in the comments section in case I miss something specific to a new version.
The first thing you need to do is set up your system paths. This is what my .bash_profile looks like:
export ANDROID_NDK_ROOT=~/Development/AndroidNDK/ export COCOS2DX_ROOT=~/Projects/Cocos2d-x/ export NDK_ROOT=~/Development/AndroidNDK/ export ANDROID_SDK_ROOT=~/Development/AndroidSDK/ export PATH=$PATH:$ANDROID_NDK_ROOT
Some parts of Cocos2D-x reference ANDROID_NDK_ROOT, some NDK_ROOT. Be as it may, we define both of them and add the path to the system path.
In order to create the hybrid project we will follow the steps below:
- create the iPhone project
- create the Android project
- merge the Android project into the iPhone project
Cocos2D-x provides a bunch of templates for both XCode3 and 4 that will create the project along with all that is needed. We will use the Xcode 4 templates in this tutorial, although I like the Xcode3 templates better.
To install the templates fire up a Terminal, navigate to the Cocos2D-x directory:
In order to install the templates you need to have root privilege, so we will call:
The terminal will then ask you what to install:
cocos2d-x template installer select the template version to install 3 for xcode3 4 for xcode4 input nothing for all
If you have both XCode3 and 4 installed, just hit enter, otherwise hit 4 for the XCode 4 templates.
Once you’ve done this, start up XCode and create a new project:
I called my new project SimpleGame so the next few examples will feature this name.
You should build and run your project now to make sure that it works properly.
A few considerations about the iPhone project
The main difference between creating an iPhone project first as opposed to an Android project is that the iPhone template will copy over and integrate the some of the Cocos2D-x framework in the project’s structure, while Android will just keep a reference to it. Android projects by default are designed to be kept inside the Cocos2D-x folder.
In the terminal get to the Cocos2D-x folder and type the following:
You will then be asked for a package path:
Input package path. For example: org.cocos2dx.example
Use something like
Then the wizard will ask you for the Android version that you want to support. Android 2.1 is a good choice:
Now cocos2d-x suppurts Android 2.1-update1, 2.2, 2.3 & 3.0 Other versions have not tested. Available Android targets: [...] id: 5 or "android-7" Name: Android 2.1-update1 Type: Platform API level: 7 Revision: 2 Skins: HVGA (default), QVGA, WQVGA400, WQVGA432, WVGA800, WVGA854 [...] id: 7 or "android-8" Name: Android 2.2 Type: Platform API level: 8 Revision: 2 Skins: HVGA (default), QVGA, WQVGA400, WQVGA432, WVGA800, WVGA854 [...] id: 9 or "android-9" Name: Android 2.3 Type: Platform API level: 9 Revision: 1 Skins: HVGA (default), QVGA, WQVGA400, WQVGA432, WVGA800, WVGA854 [...] input target id:
To select Android 2.1 in this case, type
5 and hit enter (the numbers vary based on your installed Android SDK versions). You will then be asked for the project name:
input your project name:
Type SimpleGame and hit enter. A new folder will be created with this name in the Cocos2D-x directory and the project files will be copied inside.
Careful if you created the iPhone project and saved it in the Cocos2d-x folder – it may get overwritten. The best bet is to make sure that no other folders with the same name exist in here.
And to see if it really worked you can make a build:
If it all works out without any errors we are now ready to move to the last step.
When we will be done with this chapter, the structure of the game should be something like this:
First, we are going to create a makefile to help us test if the Android build script is still working properly.
Fire up the editor of choice and create a file named makefile in the android subdirectory of the Cocos2d-x/SimpleGame folder:
clean: rm -rf libs/ rm -rf obj/
To exit and save, hit
Y, and then hit
Enter. From now on, calling
make clean in the Android directory will delete the already compiled binaries.
Do it now to clean up the compiled libraries from the previous step:
cd $COCOS2DX_ROOT/SimpleGame/android make clean
Copying over the Android specific files to the main project
The actual merging will consist of copying over some of the folders from the Android directory, adjusting some values in the build_native.sh script and modifying a file from the iPhone project.
First, copy the android folder from
$COCOS2DX_ROOT/SimpleGame/android/ to the iPhone project directory, next to the
ios folder (the final path would be
Second, copy the Android.mk file from
Third, copy the Android.mk file from
Fourth, copy the android folder from
Finally, copy the platform folder from
Sure, this will copy over the win32, marmalade, linux and other folders as well, but unless you want to hunt and peck through the folders to figure out what you need and what you don’t, just trust me on this one and copy all of them over.
Editing the Android makefile paths
Then edit the
android/build_native.sh file and update the following paths:
# set params COCOS2DX_ROOT=../libs/cocos2dx GAME_ROOT=../ GAME_ANDROID_ROOT=$GAME_ROOT/android RESOURCE_ROOT=$GAME_ROOT/Resources
Next, open up the
android/jni/Android.mk file and make it look like the following:
LOCAL_PATH := $(call my-dir) include $(CLEAR_VARS) subdirs := $(addprefix $(LOCAL_PATH)/../../libs/,$(addsuffix /Android.mk, \ cocos2dx \ CocosDenshion/android \ )) subdirs += $(LOCAL_PATH)/../../Classes/Android.mk $(LOCAL_PATH)/helloworld/Android.mk include $(subdirs)
Next, open up the
android/jni/helloworld/Android.mk file and make it look like the following:
LOCAL_PATH := $(call my-dir) include $(CLEAR_VARS) LOCAL_MODULE := game LOCAL_SRC_FILES := main.cpp LOCAL_C_INCLUDES := $(LOCAL_PATH)/../../../libs/cocos2dx \ $(LOCAL_PATH)/../../../libs/cocos2dx/platform \ $(LOCAL_PATH)/../../../libs/cocos2dx/include \ $(LOCAL_PATH)/../../../Classes LOCAL_LDLIBS := -L$(call host-path, $(LOCAL_PATH)/../../libs/$(TARGET_ARCH_ABI)) \ -lcocos2d -llog -lgame_logic include $(BUILD_SHARED_LIBRARY)
What we have done is basically update the relative paths to match our folder structure — instead of going all the way to the folder above our project folder (the old cocos2dx installation directory), we go to the root of our project and then enter the
Finally, open up the
Classes/Android.mk file and update the paths once more to match the following:
LOCAL_PATH := $(call my-dir) include $(CLEAR_VARS) LOCAL_MODULE := game_logic LOCAL_SRC_FILES := AppDelegate.cpp \ HelloWorldScene.cpp LOCAL_C_INCLUDES := $(LOCAL_PATH)/../libs/cocos2dx \ $(LOCAL_PATH)/../libs/cocos2dx/platform \ $(LOCAL_PATH)/../libs/cocos2dx/include \ $(LOCAL_PATH)/../libs/CocosDenshion/include \ $(LOCAL_PATH)/../libs/cocos2dx/lua_support LOCAL_LDLIBS := -L$(call host-path, $(LOCAL_PATH)/../android/libs/$(TARGET_ARCH_ABI)) \ -lcocos2d -lcocosdenshion \ -L$(call host-path, $(LOCAL_PATH)/../libs/cocos2dx/platform/third_party/android/libraries/$(TARGET_ARCH_ABI)) -lcurl include $(BUILD_SHARED_LIBRARY)
Now go to the android folder and type in the terminal
This will delete all the previously compiled libs and objs so they can be rebuilt by the build script. This is important! If you don’t clean up the already built libraries they won’t be deleted and the build script will complain that there’s “no rule to make target”.
build_native.sh from the android folder in the terminal and have it successfully compile.
Each and every time you want to deploy an APK to an Android device (or virtual device) make sure you clean the project from inside Eclipse (Go to Project > Clean) and then right click the project and Run As > Android Application
Cleaning the project will force Eclipse to refresh the bundle files and take into account the newly compiled code when creating the game APK.
Optional: cleaning the platform folder
The platform folder inside the libs/cocos2dx is somewhere around 115MB. Unless you want to pollute your versioning system with a lot of unnecesssary files, I suggest you clean up that folder before committing.
To do that, open up the libs/cocos2dx/platform path and delete all the folders except for ios, android and third_party. You should NOT delete any of the files however.
Next, enter the libs/cocos2dx/platform/third_party folder and delete all the existing folders except for android and ios. This should clear you up about 50 MB of space.