Friday, September 30, 2011

Quick and dirty guide to getting cocos2dx working on Android from Windows 7

Second Part: More advanced concepts of getting cocos2dx working on Android from Windows 7

This guide builds on the official guide for setting up Cocos2d-x on the Android Phone with additional explanations in the sections where the original one is outdated, incomplete or ambiguous, so hopefully no one else has to make the same mistakes I did.

First a general overview of what has to happen to see your precious game on the android phone. You create a Visual Studio project from a cocos2dx template and set it up to work with cocos2dx. Once you've got your game running and ready to test on the phone, you use a .bat file provided in the cocos2dx download to create a default android project from the "HelloWorld" project it comes with. In this new folder it creates in the android root, you override the existing classes and resources with the ones from your project, and you make sure they are in the makefile. Then you use Cygwin to compile everything into native code, and finally you create a new android project in eclipse, import the code you compiled and hopefully have it work in the phone.

It's a non-trivial process, but not that hard either, and the people at Cocos2dx have made quite an effort to get this working as it is. So, step by step.

Step by Step

Step 1: Get all the android material

Download android sdk, install it and test it in eclipse. This is a well-documented process in the android sdk website.
If you have an Android phone to test on, set it up for development and try a test application in it.
Download the android ndk and extract it to a folder with no spaces in the path.

Step 2: Get all the cocos2dx material

Download the latest version of cocos2d-x and set it up for win32 development as stated here. Download Cygwin and make sure you mark the "Devel" branch as "Install" when you download it.

Step 3: Get the create-android-project.bat working

From the original tutorial:

To adapt to my environment, I change the settings in create-android-project.bat.
set _CYGBIN=C:\cygwin\bin
The path of cygwin bin
set _ANDROIDTOOLS=D:\anroid\android-sdk-windows\tools
The path of android sdk tools
set _NDKROOT=D:\anroid\android-ndk-r5b
The root of ndk

Step 4: Creating the project

Now we create our Cocos2d-win Application form the MVS templates. If this template is not available, go back and check you did step 2 correctly. You can create this project wherever you want. For the sake of brevity, let’s assume you are creating a Pong game, and aptly name your project “Pong”. While following the cocos2dx creation template unmark every cocos2d library except Simple Audio Engine in Cocos Denshion.

Next up we need to add 3 things to make the Pong project reach the cocos2dx files it needs. Include the source files, link the library files, and copy the dll files. To make this process easier create an environment variable with the root of your cocos2dx installation. I call mine COCOS2DX and it’s defined as C:\eclipse\android\cocos2d-1.0.1-x-0.9.1\cocos2d-1.0.1-x-0.9.1.

NOTE: If you modify this variable, or any other, and want to use it from visual studio, you need to restart visual studio.

Step 4.1: Include the source files

Inside Visual Studio, with your Pong project open, right click on the project and select Properties. At the top make sure you select “Configuration: All Configurations”, otherwise you’ll have to repeat the whole process for the each configuration you’ve got (usually just debug and release).
Go to C/C++ / General /Additional Include Directories, there your template should have 9 includes already. Something like this:

  • .;
  • .\win32;
  • .\Classes;
  • ..\cocos2dx;
  • ..\cocos2dx\include;
  • ..\cocos2dx\platform;
  • ..\cocos2dx\platform\third_party\win32\OGLES;
  • ..\CocosDenshion\Include;
  • %(AdditionalIncludeDirectories)

The first 3 you can leave as-is, because they reference the project locally (including what’s in the project folder and in the win32 and classes folders. As you need these files, all is good. The next 5 however, all the ones that start with “..\cocos2dx”, assume you’re in the root cocos2dx folder. So we just correct this using our COCOS2DX environment variable.

  • .;
  • .\win32;
  • .\Classes;
  • $(COCOS2DX)\cocos2dx;
  • $(COCOS2DX)\cocos2dx\include;
  • $(COCOS2DX)\cocos2dx\platform;
  • $(COCOS2DX)\cocos2dx\platform\third_party\win32\OGLES;
  • $(COCOS2DX)\CocosDenshion\Include;
  • %(AdditionalIncludeDirectories)

To be honest, I don’t quite know what the AdditionalIncludeDirectories are, so I just leave it there.
With this however, your project knows where the cocos2dx files it needs are.

Step 4.2 : Adding the libraries

You need the .lib files that where created by compiling the cocos2d-win32.vc2010.sln, all the way back at step 2. We are going to store them locally for clarity, though you could just modify the linker path using our COCOS2DX variable.

In the Pong folder, next to the Classes and Resource folders, we create a Libs folder, and inside put two subfolders, Debug and Release.
Next we copy all the .lib files from our COCOS2DX/Debug.win32 and COCOS2DX/Release.win32 folders to the Debug and Release folders respectively.

Inside Visual Studio, with your Pong project open, right click on the project and select Properties. At the top make sure you select “Configuration: All Configurations”, otherwise you’ll have to repeat the whole process for the each configuration you’ve got (usually just debug and release).
Go to Linker / General / Additional Library Directories and you should find something like:

  • $(OutDir);
  • %(AdditionalLibraryDirectories)

We need to add the library path, so we make it:

  • $(OutDir);
  • $(SolutionDir)\Pong\Libs\$(Configuration);
  • %(AdditionalLibraryDirectories)

As long as you only have Debug and Release configurations this should work fine. Visual will go to Pong/Libs/Debug or Pong/Libs/Release and get the .lib files from there when needed. If you add more configurations, make sure to add the appropriate folder to Libs. If your project is not named Pong, modify the path accordingly.
Right now it should let you compile the project without errors but not run it. We’re missing the dlls.

Step 4.3: Adding dlls

First build your application both in release and in debug. This should create in your visual studio project debug and release folders with an executable called Pong.exe, and maybe a few other things.

Go back to the COCOS2DX/Debug.win32 and COCOS2DX/Release.win32 folders and fish out all the .dll files copying them to the Debug and Release folders in your Pong project folder respectively.
There. You should be able to build and run, seeing your project on a small window.

Step 5: Use the .bat to create an android project

This is pretty well covered in the original tutorial. Click the create-android-project.bat and fill out the package path (org.cocos2dx.Pong in our case) and the name (Pong) and finally the version to compile to (a list of versions should appear in screen).

NOTE: This step is irrelevant of your visual studio project, you don’t need to copy your Pong visual studio project to the cocos2dx root or anything. The .bat creates a folder all by itself.

Step 6: Fill in the meat

This is the step that really had me stumped until I asked in the forums. The .bat creates a new project based on the HelloWorld example in the root directory, so if you just run the bat and continue to the next step, in the end you’ll have the HelloWorld project in your phone instead of the Pong game.

Once you have the Pong folder created by the .bat in the root cocos2dx folder, you need to copy the content of your Classes folder in your visual studio Pong project to the cocos2dx Pong Classes folder, substituting the contents, and do the same with the Resources folder.

Now the files are in the appropriate place, but we still need to tell tel the makefile to take them into consideration when compiling, so we go to COCOS2DX\Pong\android\jni\helloworld\ and modify the makefile. You’ll notice that near the top of the file there is a LOCAL_SRC_FILES that already includes the path of the main.cpp and the 2 HelloWorld project files. Leave the main but override the rest so it has the paths of the files you added.

In my case:
LOCAL_SRC_FILES := main.cpp \
../../../Classes/AppDelegate.cpp \
../../../Classes/Elements/Ball.cpp \
../../../Classes/Elements/Stick.cpp \
../../../Classes/Scenes/PlayScene.cpp \

Step 6: Run Cygwin to compile

Just like the original tutorial explains

Step 7: Create a project in eclipse and import the Pong project

Just like the original tutorial explains.

Second Part: More advanced concepts of getting cocos2dx working on Android from Windows 7