Development Environment Preparation for Porting IOS Game Made Using the Cocos2D Framework to Android Part 1

Let’s get the necessary tools and sources for development – Android SDK, Android NDK, and the Cocos2d-x framework – let’s set up a basic project and support our project with version control system.

Last year our company published Sprinkfield, a logic game for IOS. You can read about the development of the game here.

Soon after, we got the idea to publish this great, addictive game for Android as well.

This is where I come in the picture. Since each of my Fedex projects was developed for Android, I was given the job of performing this conversion.

You can imagine my surprise when I realized that the framework in which Sprinkfield was developed had no supported version for Android (written in Java). Thus we decided to go with the cross-platform version of Cocos2D (cocos2d-x). What’s interesting about the framework is that it was written in C++, so it can be run under Android as native code, as well as under IOS and Windows Phone. It handles the differences in platforms admirably, thus the same code can be executed on different devices (the wrapper classes written in the operating system’s language).

I am working on the development on Xubuntu 12.10, but my workarounds (as written below) work in any other version of Ubuntu or OSX.

Because of its length, this entry series is planned for two parts.
Additionally we planned another 3 entries that have to do with this topic and the below examples:

  • useful 3rd party libraries
  • speed-up project build time
  • useful and unique tools and scripts used during development

Let’s look at the first part of the developmental process for this project:

1. Preparations

1.1 Downloading IDE and Android SDK

Android-developer-tools

For my IDE, I chose the Eclipse ADT version preferred by Android, which also contains the newest Android SDK, and the plugins crucial for development. All this can be downloaded here.

Installation is easy, you need simply to extract the downloaded zipped file and then run the IDE.

Comment: I extracted it into the folder $HOME/dev/, then I created a symlink that links the folder $HOME/android to the folder $HOME/dev/adt-bundle-linux-x86_64 (or, in the case of OSX, it links the folder adt-bundle-mac-x86_64)

ln -s $HOME/dev/adt-bundle-linux-x86_64 $HOME/android

Comment: we must put folders $HOME/android/sdk/tools and $HOME/android/sdk/platform-tools into the PATH variable, otherwise we can’t be sure that tools used later will function correctly.

1.2 Android NDK

android-ndk

The next step is downloading Android NDK, which can be done here.

We must simply extract it to the folder $HOME/android.

Thus folder android-ndk-r8d was created, for which I immediately created a symlink (yes, I really love symlinks :) ) that link to the same folder but with the name ndk.

ln -s $HOME/dev/adt-bundle-linux-x86_64/android-ndk-r8d $HOME/dev/adt-bundle-linux-x86_64/ndk

This will be useful later, if a newer version of Android NDK comes out. Then we will simply have to extract it next to the other one, delete the ndk symlink, and create a symlink to the folder of the new version, also with ndk as its name. This way we’ll be able to avoid a lot of changing of paths in our project.

1.3 Let’s get the source code of the framework!

cocos2dx_portrait

It can be downloaded zipped from the cocos2d-x homepage or from GitHub.

I recommend the first link, it will make our lives easier later. If we choose GitHub anyway, we might end up accidentally using a non-stable version that’s still under development, which would just lead to lots of confusion and anger. Why certain things don’t work the way we expect them to, I don’t know… (I can’t deny the fact that I also made this mistake :) ).

If we download the zipped version, then after extracting it, let’s rename the folder cocos2d-x. Whichever one we choose, lets make sure that cocos2d-x ends up in the folder $HOME/workspace.

mv $HOME/workspace/cocos2d-2.1beta3-x-2.1.1 $HOME/workspace/cocos2d-x

If we chose to stick with GitHub repository cloning, then let’s revert to a stable version, which can be found here (we can even download the correct versions of certain tags here). For example:

git checkout cocos2d-2.1beta3-x-2.1.1

If we got our cocos2d-x from GitHub, then we must delete the .git folder from folder $HOME/workspace/cocos2d-x/, as well as the .gitignore and .gitmodules files. It will be important later that these don’t exist.

2. Let’s create our basic project

Cocos2d-x contains a script for creating a basic project, which in this case is the create-android-project.sh file located in the folder cocos2d-x.

We altered this according to our needs. You can find our script here (along with other alterations), or you can use the original.

If you are using our altered version, just extract the contents of the attached file into your cocos2d-x folders and replace the already existing files.

What we didn’t like in the original version (we’re not saying it’s bad, it’s just a question of taste):

  • it created the project in the cocos2d-x folder
  • it depended on environmental variables, if we agree on the location of sdk and ndk ($HOME/android/sdk,ndk), then we can use them on different developers computers as well
  • it created a proj.android folder in our project, instead it should be a folder name more relevant to our project

Upon entering folder cocos2d-x, let’s execute the following command:

./create-android-project.sh

The process will ask for the data of our application, and will then create the folder structure for it, with the cocos2d-x HelloCpp example code within.

3. Setting up of version control system

ralph2
CCScene* HelloWorld::scene()
{
    // 'scene' is an autorelease object
    CCScene *scene = CCScene::create();

    // 'layer' is an autorelease object
    HelloWorld *layer = HelloWorld::create();

    // add layer as a child to scene
    scene->addChild(layer);

    // return the scene
    return scene;
}
fix1

During the development, we will often destroy already functioning things, much like Wreck-It Ralph. It’s during times like these that we will need our very own Fix-it Felix, ie. version control system :)
Of course its main function is not to undo our errors, but we will often use it for such a purpose.

Our developer team prefers Git, so from here on out, I will be approaching things from a Git-specific perspective.

We must first specify a storage space, where Git can store our projects. This can be located on another computer, that we reach via ssh, or it can be a folder on the computer we are working on (not to be confused with the folder $HOME/workspace – we need a different one)

pl: $HOME/git

3.1 Our own cocos2d-x repository

Let’s initialize our own cocos2d-x repository.

We must enter the terminal and navigate to the folder specified in the previous point.

cd $HOME/git

We can initialize the repository with the following command:

git init --bare cocos2d-x.git

After this, let’s rename the $HOME/workspace/cocos2d-x.

mv $HOME/workspace/cocos2d-x $HOME/workspace/cocos2d-x-tmp

Then let’s run the below commands:
(for me $HOME/git was the folder containing the git repositories in the example)

cd $HOME/workspace
git clone $HOME/git/cocos2d-x.git
cp -R cocos2d-x-tmp/* cocos2d-x/ && cp cocos2d-x-tmp/.gitignore cocos2d-x/ && rm -R cocos2d-x-tmp

We wrote our own .gitignore, one that fulfilled our needs. This is also included in the above mentioned zipped file (the one containing all of our cocos2d-x relevant changes, downloadable here ). If you downloaded and extracted it earlier, it will be in place after running the above commands.

Once we’re done with this, let’s commit our own cocos2d-x repository with the below commands:

cd $HOME/workspace/cocos2d-x
git add -A && git commit -m "first" && git push origin master

Our own cocos2d-x repository was created, this will come in handy later.

3.2 Our project’s repository

Let’s create a new repository for our project using the above mentioned process. Let’s call it HelloCocos2dx

cd $HOME/git
git init --bare HelloCocos2dx.git

After this let’s rename the $HOME/workspace/HelloCocos2dx folder.

mv $HOME/workspace/HelloCocos2dx $HOME/workspace/HelloCocos2dx-tmp

Let’s run the commands below:

cd $HOME/workspace
cp -R HelloCocos2dx-tmp/* HelloCocos2dx/ && cp HelloCocos2dx-tmp/.gitignore HelloCocos2dx/ && rm -R HelloCocos2dx-tmp

We created our own .gitignore file for the project. The creation process will copy this into our project. We must copy this into the $HOME/workspace/HelloCocos2dx folder.

Once we’re done with this, let’s commit our own HelloCocos2dx repository using the below commands:

cd $HOME/workspace/HelloCocos2dx
git add -A && git commit -m "first" && git push origin master

Our own HelloCocos2dx repository has been created! HURRAY! :)

Let’s bind our cocos2dx repository, so if other developers clone the HelloCocos2dx repository, they won’t have to search for the relevant framework.

The easiest way to do this is to bind cocos2dx as a git sub module, and then we download it.

We can do this using the below command:

cd $HOME/workspace/HelloCocos2dx

git submodule add $HOME/git/cocos2d-x.git

With this, we have completed the setup of our version control. We can add additional sub modules using the above process.

Summary

In this entry, we acquired the tools and resources necessary for development.

We created a basic project, in which we can later work, and we supported it with version control.

In part 2 of this entry, we will set up our project within the ADT Eclipse development tool, using functioning code completion.

Facebook0Twitter0Reddit1Google+0LinkedIn0tumblr