Wednesday, February 25, 2015

Cocos2D-X Game Development in Android Studio

When we create a new Cocos2D-X project using Cocos2D-Console, an Eclipse project is generated by default. The problem is that Google has dropped support for Eclipse ADT, they're pushing IntelliJ Idea based Android Studio with full force.
In this post I will show you how to convert your Cocos2D-X Android Eclipse ADT game project into Android Studio project, how to configure NDK and JNI in Android Studio to run your game from Android Studio directly.

Note: A reader recently commented that he was using Cocos2D-JS on Linux, this article was useful in resolving his problem. Things tend to get buried in comments section, that's why I am putting an important fact inside the post. I highly recommend you to read the comments section, it has got some useful bits of information.

Important

 Do take a look at the previous article in this series, the link is given below. This article explains important concepts like setting important environment variables like NDK_ROOT. The same article also shows you how to compile a project in now obsolete Eclipse ADT. A quick look will be helpful I hope.

Compile Cocos2D-x Project For Android Game Development


Create a new Cocos2D-X Project

First of all, let's create a brand new Cocos2D-X game development project, you may skip this part if yo already have a project. Run the Cosos-Console command.
cocos new -p com.honesitconsultancy.indiegame -d "D:\Cocos\Projects" -l cpp "IndieGame"

Fig 1: Cocos-Console New Project


Once the command line operation is done, you will have a new project folder named "IndieGame" on path "D:\Cocos\Projects\". The folder will look like the screenshot below:

Fig 2: Cocos2D-X New Project Structure

1. Import Android project into Android Studio

Run Android studio, if you already have a project opened close it. Otherwise, it will show the project selection dialog exhibited below:
Fig 3: Android Studio New Project Dialog


I've blurred the project names on left to hide names of a few client project I'm providing consultancy through oDesk.


  1. Click on the item "Import project(Eclipse ADT, Gradle, etc.)
  2. Project selection dialog will open. Browse to your game path, in my case it was "D:\Cocos\Projects\IndieGame\". The sub folder "IndieGame" was not being shown by the user interface, I had to click the refresh button.
  3. Select the Android project generated by Cocos-Console command line. The name currently will be "proj.android". The refresh button is highlighted by a circle, the Android project is shown by an arrow.

Fig 4: Select Project Dialog Android Studio

The next dialog will ask for a path to save the new Android Studio project. You must keep the new project alongside the other projects.
Fig 5: Android Studio Select Destination Path

  • Change the name of project folder to proj.androidstudio and click Next

You'll see a few options on next screen. Android Studio is trying to help you, we don't need it though. check all 3 check-boxes reading "Replace jars with dependencies, when possible"; "Replace library sources with dependencies, when possible"; and "Create Gradle-style(camelCase) module names" on the next screen, as shown below. Click Finish button.

Fig 6: Android Studio Import project from ADT Options


The Android Studio will ask that the directory does not exist and do you want to create it? Click "OK" and a new directory/folder will be created for you.

2. Add NDK to your project properties

Android Native Development Kit(NDK) path will be added to your the "local.properties" Android Studio project file, it is an auto generated file.
Click on the proj.androidstudio name on top left of your screen, and select local.properties as shown in the screen grab below.
Android Studio Open local.properties


By default this file will contain the path to Android SDK, don't mess with it. We need to add a line of text below the existing SDK line.
The format of the NDK entry will be ndk.dir=%Path of your NDK directory%
In my case, the precise statement is shown below:

ndk.dir=D\:\\cocos\\android-ndk-r10d-windows\\android-ndk-r10d

Important: Windows users must modify the path string and add backslash in following places:
  • Right after the drive letter
  • Right every backslash in the path
Save the local.properties file and close it.

3. Modify Build.Gradle to handle JNI

  • On top left, click proj.androidstudio
  • Click IndieGame(or whatever project name you've chosen)
  • Click build.gradle




Add a new line right after closing bracket } pertaining to defaultConfig section.
Add following magic lines down there:

sourceSets.main
            {
                jni.srcDirs = []
            }
The sourceSets.main line will enable use of Java Native Interface or JNI in your project. JNI does same thing as Interop on Microsoft .Net.









Running your Cocos2D-x Indie Game on Android Devices

We need to perform just one more step before hitting the build icon.

  • Open command prompt.
  • Change directory to the location of your project.
  • Once there, type following cocos-console command

cocos compile -s ".\proj.androidstudio" -p android --ndk-mode debug

Be Patient: I got a system with Core-i7 CPU and 8 GB RAM, my system takes about a minute to compile the code. If someone's got a slower/older system, getting a cup of coffee while the code is compiling is a good idea.

4. API Level 9 Error

By default the Cocos-Console generates a project with Android SDK level 9. Its an old platform, if you don't have installed on your system Android Studio will show an error. To fix the problem, you'll need to modify the Android SDK level values in your game Manifest.xml and Gradle configuration file.

4a. Changes in Gradle Build File


  • Luckily you would already have the Gradle file opened to make half of the changes(otherwise follow Modify Build.Gradle to enable JNI section above). Find the defaultConfig section shown below and change values accordingly. I got platform 14 installed so I changed it to 14.


defaultConfig {
        applicationId "com.honesitconsultancy.indiegame"
        minSdkVersion 14
        targetSdkVersion 14

        ndk {
            moduleName "cocos2dcpp_shared"
        }
    }


  • Change the compileSDKVersion value as well. By default it was 10, I'll change it to 14.
  •     compileSdkVersion 14
Save the file.

4b. Changes in Android Studio Manifest File

Now open the Manifest file, you can do so by clicking project name hierarchy as shown by the thunderbolt in the screen grab below(proj.androidstudio -> IndieGame -> src -> main). I replaced the arrow, it looked boring :)


We need to change the minSDKVersion property here. We'll change it to 14(or any suitable SDK platform level you got installed).

<uses-sdk android:minSdkVersion="14"/>

After changing the value, save the manifest file. And hit the Synchronize button as well.

Make The Project

Here comes the climax!

Click the "Build" menu and select "Make Project" menu item. You may use shortcut key Ctrl + F9
Again, just stay calm and wait for a while as the project is being make.
Click "Run" button, or use shortcut key Shift + F10.

Note: I assume you've already configured a phone or emulator to work with your Android Studio, how to do so is beyond the scope of this article.

Once your blank Cocos2D-X game project starts running following screen will be displayed by default:
Please feel free to post comments on this blog, do check other articles in this series. You may contact me via e-mail using the form on left top of this post.
I will be posting more stuff, you better subscribe to the mailing list.

29 comments:

  1. Thank you for the effort to creating this valuable source of information.

    ReplyDelete
  2. Hey Naeem.

    Thank you so much for this invaluable tutorial. I have dedicated all this week to setup a cocos2d-x program and finally got to your site, which is very well explained and detailed.

    Sadly, I have one minor issue with the whole process. I was thinking to send you an email, but I prefer to publish it online so other people can benefit from it. I will also be detailed.

    A small background. I installed yesterday the last version of Android Studio. I followed this tutorial (before knowing yours) https://www.youtube.com/watch?v=B9ObAzm6rnQ which got me started with the installation.

    Basically, I download the cocos2d-x, I installed Android Studio (no more Eclipse) Python version 2.*, Apache Ant and Android NDK. After installation, I followed the rest of the tutorial but never got something working.

    I happily found your site. I made many modifications to my installations, including versioning problems, which got me hooked for many hours (modifying or reinstalling them) But, at the end I got them solved. I could compile a cocos2d-x program and then start following your tut.

    I followed your tutorial very smoothly. I got everything as you said. But, at the moment of compiling, I got an error at synchronizing the build.gradle file. When I try to build it, I get an error:
    Error:(17, 0) Could not find property 'sourceSets' on root project 'proj.androidstudio'.

    It takes me to that file and points me the error in (appears with a different background color):
    dependencies {
    classpath 'com.android.tools.build:gradle:1.1.0'
    }

    I discovered that the problem is also in the build.gradle file in this place (which also has a different background color):
    dependencies {
    compile project(':libcocos2dx')
    }
    Which when I try to sync, it throws the same error. If I mouse over it, it reads:
    'dependencies' cannot be applied to '(groovy.lang.Closure)'

    I went to Many places on the net and spent time looking for answers before coming here. I modify many properties of the files you also modified, but mainly I found out that I had some missing properties inside the build.gradle file. I grabbed many modified build.gradle files I found and at the end I modified like this:

    compileSdkVersion 24
    buildToolsVersion "24.1.2"

    minSdkVersion 10
    targetSdkVersion 24
    versionCode 1
    versionName "1.0"

    runProguard false
    proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'

    targetSdkVersion gives me an error if I put it in 14, reads "Not targeting the last version of Android" That's why I changed it to 24, the same as the other ones.

    I am completely new to this world, but following your tut and looking to solve the problems I have encounter have helped me to understand more about all this (not yet cocos2d-x though, but soon I will)

    I feel that it has to be a minor problem, maybe related to the libcocos2dx dependency, I guess.

    Anyways, thank so much for your time and effort Naeem. I will be very close to your tuts, they are really wonderful!

    ReplyDelete
  3. Wow!

    That's a lot of appreciation, thank you very much. I am also learning Cocos2D-x as a hobby and writing stuff (yet another hobby) down as I go.
    You made the right choice by posting your message in public.
    I am happy to know that you overcame a critical issue. Your comment is complementing the blog post and it is going to be very helpful for others in days to come.
    Stay in touch, feel free to talk back and share ideas.

    Regards,
    Naeem.

    ReplyDelete
    Replies
    1. Hey Naeem, thanks so much for your response.

      I am happy to know that I am able to help. I run an international game dev forums and I know that people really appreciate both those who make this wonderful and detailed tuts, and those who add value to it.

      You know, I am still trying to overcome the compiling issue but still with no success. I tried to do a fresh start many times, making some modifications to try to see what is the problem, but I get the same result.

      Did you ever get the same issue? It still throws me an
      'dependencies' cannot be applied to '(groovy.lang.Closure)' error.

      I am also looking on the cocos2d-x official forums. I just found out that a contributor create an empty project for Mac with Xcode (I haven't tried though), here is the link.
      https://github.com/FenneX/FenneXEmptyProject

      I wish it helps. In the meantime, I will continue my research. Let us know if you have something. Also, if I get something I will let you know.

      Keep having a wonderful day Naeem. And again, thanks for your presence.

      Delete
  4. Jose,

    I am under intense demo/release pressure these days. Hopefully I will be able to get back to Cocos some time soon. I really want to but can't find time to continue the game programming series for now.

    Cheers,
    Naeem.

    ReplyDelete
  5. Naeem thanks for your message.

    I completely understand. I will continue doing my research, I have learned many good things on the path.

    Keep having a great one!

    ReplyDelete
  6. Great Tutorial, Thanks for your valuable information. I have been looking for this for two days

    ReplyDelete
  7. Thank you very much for the appreciation Edwin. Please share the link with your friends on Facebook, Twitter, LinkedIn, and any other forums that you find suitable. It will be a huge favor.
    I will experiment with the newer version of Android Studio some time soon and share it here, the new version's got support for C++. That means, we will be able to write C++ code right in the Android Studio!
    Hopefully the Cocos2D-x team will update their utilities so that new Android Studio C++ projects can be created easily.

    ReplyDelete
  8. When i tried running the "cocos compile" command on cmd, I go the following error :

    Android platform not specified, searching a default one...
    Can't find right android-platform for project : "/Users/filipeferminiano/MyCompany/MyGame/proj.android". The android-platform should be equal/larger than 10

    ReplyDelete
  9. Saswat,

    Did you see the section " 4. API Level 9 Error" in this post? I believe you need to download and install appropriate version of Android platform SDK which is >= version 10.
    Most probably installing API level 14 and putting that in all places as described in the aforementioned section will resolve your problem.

    ReplyDelete
  10. Hi,

    Thanks for the tutorial. It worked for me and I am able to convert project to gradle.

    But my only problem is I am not able to compile the proj.androidstudio using cocos command. I am using following command to compile
    "cocos compile -s ".\proj.androidstudio" -p android", but still cocos is compiling my proj.android. It is not taking the proj.androidstuido.

    Can someone help me. Thanks.

    ReplyDelete
  11. Sateesh
    as far as I remember there was one more step before running the compile command. I am unable to write the exact step down right now, because I don't remember what it was. I am unable to find what the command was anywhere. I will check later in the evening, 5:00 AM here and I need to run for office. I am in village right now.
    In the meanwhile, keep trying and let the community know if you find anything.
    Thanks,
    Naeem.

    ReplyDelete
    Replies
    1. Sure Naeem will try for the solution and update here if I am successful.

      Delete
    2. Hi, I was having the same issue.

      Turn out I just has have to compile the ".\proj.android" first BEFORE importing into android studio.

      I don't know whether that will be problematic though.

      Delete
    3. Hi, Is there any solutions for this problem? After I have modified source in ./Classes and compile project ./androidstudio, but cocos still compiles in folder ./android. New sources are not effective in Android Studio

      Delete
    4. Can anybody help HT? I am sorry I've been busy with other stuff and didn't do much Cocos lately. Can't help :(

      Delete
    5. I am having this same issue! Holy s$*^# must have spent 30+ hours on this issue (compiling in android studio) and I'm getting very frustrated

      Delete
    6. Maybe you need a break and look at the problem with a fresh mind some time later. :)

      Delete
  12. I'm using cocos2d-js on linux, and this is exactly what I was looking for. It works great! I didn't run into any issues.

    ReplyDelete
  13. Dear Bruce, its a pleasant surprise for me. I didn't know it would work on Linux or not, but now I know it does :)
    Thanks very much for your feedback.

    ReplyDelete
  14. I hope this helps someone following this tutorial. This is the install setup I have:
    Everything was downloaded/installed on 7/10/2015 - if you're reading this within a few months or maybe even a year or so, hopefully this can still serve you:
    Android Studio 1.2.2
    android-ndk-r10e
    android-sdk-windows
    apache-ant-1.9.6
    cocos2d-x-3.6
    Java - Java Runtime Environment (JRE) and Java Development Kit (JDK) - "gave me C:\Program Files\Java\jdk1.8.0_45" and "C:

    \Program Files\Java\jre1.8.0_45"

    I encountered a handful of problems trying to follow the tutorial. Here's a list of problems and solutions.

    --------

    #1

    Upon compiling, I got an error for java:
    Unable to find a javac compiler;
    Perhaps JAVA_HOME does not point to the JDK.
    I had to manually set the environment variable JAVA_HOME to point to the jdk1.8.0_45 folder. Then it compiled successfully.He mentions sdk level 14, but I had level 22 (I had android-22 in the sdk\platforms folder) so I used 22 instead of 14 everywhere.

    --------

    #2

    Problem:
    When I start up Android Studio (automatically loading my project), it shows error:
    Error: failed to find target android-10

    Solution:
    Edit the build.gradle for libcocos2dx (proj.androidstudio->libcocos2dx->build.gradle) and substitute for my version 22 in the three lines mentioning sdk version. Then restart Android Studio and the error message goes away.

    --------

    #3

    Problem:
    Android Studio gives warning:
    WARNING [Project: :BoxPusher] Current NDK support is deprecated. Alternative will be provided in the future.

    Solution:
    I ignore this as it is only a warning and at the end says BUILD SUCCESSFUL.

    --------

    #4

    Problem:
    When I hit Make Project I got the following:
    Error:FAILURE: Build failed with an exception.

    * What went wrong:
    Task '' not found in root project 'proj.androidstudio'.

    * Try:
    Run gradle tasks to get a list of available tasks. Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output.

    Solution:
    In file proj.androidstudio.iml, remove:
    <facet type="android" name="Android">
    <configuration>
    <option name="ALLOW_USER_CONFIGURATION" value="false" />
    </configuration>
    </facet>
    Note: I added the facet stuff back after restarting Android Studio (or computer) and the problem didn't come back. Perhaps restarting things fixes some problems.

    --------

    #5

    Problem:
    After successful build, I click Run 'MyProject'. I chose default virtual device, Nexus 5 API 22, (x86). The program crashes right away. Virtual device shows: "Unfortunately, MyGame has stopped." Before hitting "OK" on that screen, Android Studio says:
    java.lang.UnsatisfiedLinkError: dalvik.system.PathClassLoader[DexPathList[[zip file "/data/app/com.mycompany.mygame-2/base.apk"],nativeLibraryDirectories=[/vendor/lib, /system/lib]]] couldn't find "libcocos2dcpp.so"

    Solution:
    Upon investigating, it seems that libcocos2dcpp.so is only generated in proj.android (not proj.androidstudio) under libs/armeabi/libcocos2dcpp.so - I couldn't figure out how to get libcocos2dcpp.so to my proj.androidstudio project. To solve this, when creating the project in Android Studio (using import project as described in tutorial), I used the same destination folder (proj.android instead of proj.androidstudio), selecting "yes" to overwrite existing files. I still followed the remainder of the tutorial.

    --------

    #6

    Problem:
    When running it now (after using solution from #5) in the default created Android Virtual Device, Nexus 5 API 22 x86, the app crashes with a debug message complaining about cocos2d for x86.

    Solution:
    Since cocos2d is for RAM, it won't work on x86. Test it with an ARM device instead. e.g.: Nexus 5 phone, API level 22, ABI armeabi-v7a (Android 5.1.1).

    ReplyDelete
  15. Dear Fabian,
    Thank you very much for your response. Your comment was worth a blog post in itself! I will see if Google does not mark it as plagiarism, I will add it to main blog posts and put a link herein. I'm sure will be helpful for a lot of folks out there.
    Good work my friend. Please keep sharing with the community.
    Regards,
    Naeem(author).

    ReplyDelete
  16. Greetings angd salutations.
    Ive been tryin to figure what im doing wrong.
    When i first used your guide i managed to compile my project without that much problems and i managed to get tit o actually run on my virtual device. Then it started to stop updating the files after i compiled in the console. so i always keept gettign the old version installed on my virtual device. Now i just dont know how to compile anymore and test in my virtual device. It just seems to say "Unfortunatly "appname" has stoped

    I really liek to use an IDE to code and debugg in besides compiling in console and tehn trial and errro find my errors with my tablet.
    so tl;dr
    My clean project doesnt start in the AVD after compiling and following the guide you wrote here.
    When i write compile im in the project root folder ex Project Cookie
    f:\projects\cookie> cocos compile -s ".\proj.androidstudio" -p android --ndk-mode debug
    Im using:
    cocos2d-x 3.7
    Windows 10
    apache ant 1.9.6
    android ndk r10e
    Android studio 1.3
    im trying to install the test on a minimum api 22 AVD

    Any help at all would be greatly apprecited.
    And thank you :)

    ReplyDelete
  17. Hi,

    I[writer of this blog post] humbly present you my online video courses for free, each is worth $9. If you're interested in C# .Net do watch these courses.

    First one is about TCP/IP socket programming in C# .Net.

    https://www.udemy.com/tcpip-socket-programming-for-coders-using-csharp-net/?couponCode=PAKISTAN

    Second one is about Windows Service Programming in C# .Net.
    https://www.udemy.com/windows-service-programming/?couponCode=PAKISTAN

    I hope you'll find these courses useful.

    Regards,
    Naeem.

    ReplyDelete
  18. One more thing, I am seriously thinking to learn some more Cocos-2dx and put out a course in months to come. Do let me know what do you think about that as well.

    ReplyDelete
  19. Thank you so much for the information.

    ReplyDelete
  20. I have written an updated tutorial detailing the steps to install cocos2d-x on Windows, Linux and macOS. You can find this tutorial at the following link: http://vigogames.com/2017/01/23/installing-cocos2d-x/ . If you have already installed cocos2d-x and you are struggling to create a new project, I have also written a tutorial detailing the steps to take for creating a new cocos2d-x project. You can find that tutorial at the following link: http://vigogames.com/2017/01/25/starting-a-new-cocos2d-x-project/. I hope these tutorials will help someone out there.

    Cheers!

    ReplyDelete
  21. Hi,

    Thank You very much...
    Very simple and nice tutorial.

    --Mandeep Yadav


    ReplyDelete

Feel free to talk back...