Update: This code is using an outdated version of the Cocos2D port. It’ll still work if you use the sample download linked at the end – but it’s using outdated API calls. Unfortunately I don’t have time to update the tutorial to the new release of Cocos2D. Sorry guys

Cocos2D is a fantastic library / game engine for numerous platforms from PCs to smart phones. It supports the vast majority of the features necessary to make almost any 2D-based game, it even includes a fully-featured physics engine!

As part of learning Cocos2D for Android I followed Ray Wenderlich’s tutorials for the iPhone port of Cocos2D. Of course we’re dealing with Android here, so here is his tutorial recreated for Android. Ray deserves all credit for this tutorial – the tutorial is originally his, this is merely a port to Android. Credit should also go to Sketchydroide for his basic template for Cocos2D on Android.

Downloading and Installing Cocos2D

I’m going to assume you’ve already got the Android SDK installed, along with Eclipse. If not, you can follow the guides at Google. You’ll also need to test with a real device, the emulator is far too slow to test Cocos2D applications, even one as simple as this tutorial. I’m also going to assume you know Java, otherwise you’re going to get lost very quickly. There are plenty of Java tutorials out there, don’t worry we’ll wait here while you learn. The basics of Android (such as what Activities are, etc.) are helpful to know, but not critical.

First you need to download cocos2d-android-1. I’m going to assume you’re using the pre-compiled library (the .jar), although you’re welcome to include the full source code if you wish. In fact when you’re developing on your own, the source code is a better option since you gain full documentation along with the ability to tweak the code should you need to.

Open up Eclipse and create a new Android Project:

Now you need to copy the cocos2d-android.jar file into the ‘libs’ folder of your project. If the folder doesn’t exist, create it.

Next download fps_images.png and put into the assets folder of your project. You are now setup with Cocos2D!

Initial Setup

Next you need to put some code into your default activity (SimpleGame) so that you can start making your game. At the top of the class add a protected field:

protected CCGLSurfaceView _glSurfaceView;

At this point Eclipse may be moaning about the line you’ve just added. This is because you haven’t imported the namespace. The easiest way to do this is to press CTRL+SHIFT+O. Any time you use a new class, try pressing this key combination any time a completed line has an error to do with missing identifiers. Next replace the onCreate method with the following:

This is the initial setup for Cocos2D. First we tell Cocos2D which surface to render to (the OpenGL surface we set up earlier). We then ask Cocos2D to display the FPS and to run at 60fps. Note that the 60fps is our animation interval, not the framerate of the application itself which is often limited by the device.

These notify Cocos2D with what’s going on with the device – such as when the user has switched to another application or the game is being stopped by the OS.

This is all the setup we really need. You can run the game now, but it won’t display anything at this early stage (we haven’t even set up a hello world scene!).

Adding a Sprite

Sprites are small images in 2D games that move about. These can be characters, projectiles or even clouds. In this game we’ll have three separate types of sprite: Player, target (enemy), and projectile. First we need a graphic to use! You can either create your own, or use the tasty graphics provided by Ray Wenderlich’s wife: Player, Projectile, Target. Place your sprite graphics within the ‘assets’ folder of your project.

Now we need to place the sprite on the game screen. Cocos2D has an inverted coordinate system to what you’re used to – the origin is the bottom left of the screen. So as X increases you head to the right of the screen. As Y increases you go up the screen. Additionally by default the origin / anchor point of sprites is in the centre. The coordinate system is the same regardless of the platform you run Cocos2D on. The following graphic should help you visualise the coordinate system of Cocos2D:

Enough boring theory, let’s get some code down! Add a new class to your project, call it ‘GameLayer’ and make it extend ‘CCLayer’. Add the following static method at the top of the class declaration:

Now when you run the application you should have a nice white background.

Moving Targets

While it’s cool to display a single ninja, because well, ninjas are cool – we don’t yet have much of a game. What we really need are some targets for our ninja to throw stars at. While we’re at it we might as well make them move to give them a fighting chance. What we’ll do is create the targets off the screen to the right, then have them move to the left of the screen at varying speeds. Add the following method after the constructor:

The code is rather verbose to make it as easy to read & understand as possible. Near the bottom we’ve introduced a new concept: Actions. Actions are a very accessible way of getting sprites to do things without constant babysitting. You can get sprites to move, rotate, fade, jump, etc. We use three different actions in this method:

CCMoveTo: The CCMoveTo action moves a sprite from its current position to a new one. In this case we’re moving the sprite from just beyond the right edge of the screen to just beyond the left edge of the screen (remember the origin of a sprite is the centre, hence why we divide the width by two). The duration is specified in seconds between 2 and 4. As an exercise, try changing the type from int to float so we aren’t restricted to whole seconds.

CCCallFuncN: The CCCallFuncN action allows you to specify a callback. The ‘N’ means this action allows you to specify a parameter.

CCSequence: This is a rather special action in that it doesn’t do anything itself. Instead it lets you run a sequence of actions, one after the other in a linear fashion. We use this so that we can move the sprite, then when the movement has finished call our callback.

The eagle-eyed may have noticed that we have a callback, yet the method doesn’t yet exist! We better correct that right now, add the following method to our class:

This method will remove the sprite when it has finished animating to the left of the screen. The second parameter is to ‘cleanup’ the sprite, this means it is completely unloaded and we get the memory back. In a real game you would only clean up a sprite as a last resort, re-using a sprite is much better from a performance perspective. We’re going down the wasteful route to make the concept of the game as simple as possible – simple is good when learning!

Now we have code to create and animate targets, but we never call this code! What we’ll do is spawn a new target every second automatically giving the ninja plenty of shuriken practice. Add the following line of code to the bottom of the constructor:

this.schedule("gameLogic", 1.0f);

Also add the following new method to the class:

public void gameLogic(float dt)
{
addTarget();
}

Now run the application and we should have some action:

Shooting Projectiles

I like to be able to shoot my targets, so let’s add some shooting! We’re going make things simple by having the user tap to shoot, where you tap is where the projectile goes.

We’ll use CCMoveTo to animate the projectile just like how we animated the targets. The problem is, CCMoveTo requires a destination to move to, but we can’t use the tap location since that means the projectile would stop in the middle of the screen. What we need to do is use the tap as a direction, rather than a destination.

This should look familiar to anyone who didn’t fall asleep in maths class – Pythagoras! Now before we fall asleep with yet more theory, let’s start coding. In the constructor add the following line:

What we are doing here is first enabling touch support. We’re telling Cocos2D that we are ready to handle touches for the current layer. Next we add code to handle touches from the user.

First we get the coordinates of the touch itself, and convert to the Cocos2D coordinate system. This method should work regardless of the orientation of the device.

Next we create the sprite and position it over the ninja. We then work out where the projectile should move to by extending the tap off the screen. This is done by getting the X and Y offset of the tap to the projectile’s starting position. We then get the ratio of Y to X, and simply scale the touch Y coordinate to match the scaled up X coordinate (which is just off the screen). The only problem with a simple algorithm like this is that the projectile must reach the right edge of the screen before it’s cleaned up, the projectile could leave the screen (top or bottom) long before it hits the right edge. There are solutions to this problem, but they’re beyond the scope of this tutorial.

After working out the destination, we need to work out the duration of the movement – we can’t have projectiles taking different amounts of time just because of the angle they’re shot at. To solve this problem we use Pythagoras to work out the distance the projectile needs to travel, then divide that by the velocity we want. This is because velocity = distance over time, or by re-arranging: time = distance over velocity.

Finally we run the actions on the projectile. Run the application and you should be able to start shooting shurikens!

Collision Detection

It’s no good if you can shoot shurikens, but they don’t actually do anything! To solve this problem we need to add some collision detection. To keep things simple we’ll use simple bounding box collision detection rather than the other more exotic methods Cocos2D provides.

To be able to run collision detection we need to be able to keep track of all of the sprites we have. Add the following fields to the top of the class declaration:

If you run the project now you shouldn’t notice any difference – but now we’re tracking all of our sprites! This gives us a great deal of extra power, and we shall use this power to add some collision detection. Add the following method to the class:

This is a brute-force approach to collision detection. Basically we iterate through all of the projectiles and targets, creating a rectangle for each and then checking if they intersect. If there is an intersection we remove the sprites from the scene and arrays. We use the ‘toDelete’ arrays since we can’t manipulate an array while we’re iterating through it in the manner we’ve chosen. Before the collision detection will work, we need to schedule the method to be called every frame. Add the following line at the bottom of the constructor:

this.schedule("update");

Finishing Touches

We’re pretty close to a fully working game now (albeit a simple one!). All games have sound effects of some sort, and this one is no exception! First we should talk about the audio formats Android supports, since Cocos2D can’t do anything about the supported audio formats on the platform it’s running on. The current port of Cocos2D on Android doesn’t contain a full sound engine yet, certainly not on par with CocosDenshion offered on the iPhone. For this reason we’ll use basic wav files for this tutorial. We’ll also add some additional code logic so you can win/lose.

First you’ll need to get some audio for the background music and a sound effect for the shurikens. You can source your own, or download the wav version of the background music, and pew pew sound effect from Ray Wenderlich’s tutorial. Put the wav files in the res/raw folder of your project.

In the constructor add the following code after the addChild(player) line:

Gimme The Code!

Where To Now?

This project provides a good basis for further development. Some possible changes were mentioned as part of the tutorial, others are limited only by your imagination! Check out the test projects that come with the source of Cocos2D, see if you can integrate some of them into the project here.

It could be you’re using an older copy of the library. Try downloading the source files for Cocos2D and directly adding them to your project (copy the ‘org’ folder into your ‘src’ folder, then press F5 while the src folder is selected in the project explorer), making sure to remove the reference to the jar file. This should resolve any missing functionality, while giving you extra help when typing in Cocos2D code (Eclipse will automatically display the javadoc comments for you).

Hi Dan,
I had been following Ray Wenderlich for quite some time and was wondering if there were something similar for android as well. Thanks to you, we have it now. I haven’t started working with the Cocos2D-Android yet, but will be starting pretty soon, and then maybe I’ll bombard you with a lot of Questions. . For the time being, just want to thank you (and Ray as well) for your great efforts.

Hey Dan,
I was just working out with the source and found a few issues on my side. I think we don’t need the onCreate() method in the GameLayer class, as then it would need to extend the Activity super class as well. Besides we already have the GLSurfaceView in the default (SimpleGame) class. Also, the “scene” has not been created in the GameLayer, so we won’t be able to access it through

Abhimanyu, thanks for going through the tutorial! You’re quite right with the onCreate, I’m not sure why it’s even there (in the sample download it isn’t). It was probably when moving content around in the doc – I’ll make sure to remove it, good catch!

The scene isn’t created in the game layer, but it is created in a static method for convenience. It creates the scene as you’ve done, but also automatically creates the GameLayer and adds it before returning the complete scene. You could definitely use your method, but make sure to create an instance of GameLayer and add it to the scene.

The manifest doesn’t require anything special – Eclipse will create it for you with the project. Download the source code provided at the bottom of the tutorial for a working copy that you can inspect if you’re having trouble with your manifest.

> The scene isn’t created in the game layer, but it is created in a static method for convenience.

This bit confused me. By doing “runWithScene(GameLayer.scene()) it means that your SimpleGame class can’t then access/interact with the scene that’s being displayed.

I tried calling methods or moving sprites on my gameLayer object from outside, but frustratingly, nothing was being reflected on screen. I solved it by adding “public static CCScene scene” to the GameLayer and doing ‘scene.addChild(this)’ in the instantiation method.

Then, when switching scenes I do “runWithScene(gameLayer.scene)” and I can later call “gameLayer.doSomething()” and see the results displayed. I might be forgetting my object-oriented programming, so was it necessary what I did? Thanks for the great tutorial by the way.

Chris, you have found the fatal flaw with the architecture of the tutorial! To keep it simple everything is kept within the layer code itself. In a real game you would ideally move all of the game logic out of the layer (since that’s a UI construct – not a game logic construct). What you’ve done is a very elegant solution to the problem of accessing the game code within the confines of the existing architecture. However, I would recommend going with your own solution rather than the tutorial’s for your actual game (which I think you’re doing anyway).

Very Good Tutorial^^
I’m Korean. And my English is very poor.
But this article’s english level is very easy to me^^
I want make simple Role-playing game in Android platform using openGL or Cocos2d.
Please write more Tutorials ^^

hello its very good tutorial!
but i want the code to move the player from top to bottom and it can fire in straight direction!
and target should also move from bottom to top instead of right to left!
pls guide me if u can , its urgent!
Thanks

I’m afraid that’s a little out of the scope of the tutorial, however I can hopefully point you in the right direction. Changing the target direction is easy, you just switch the X coordinate for the Y coordinate. The caveat with this is the origin of the game screen is in the bottom left, so the Y coordinate increases as you go up the screen (at the moment we count down to 0, instead you’ll need to increase the Y coordinate from 0 to the height of the screen).

Moving the player is trickier, depending on how you want the player to move. The easiest would be to pick up each touch on the screen (as we already do) and use a MoveTo action to move the player. You should leave the X coordinate as is, and just make the new Y coordinate match the Y coordinate of the touch. Once the movement has completed, you can create a shuriken and have it move from the left of the screen to the right of the screen with a MoveTo action. In this case you’ll leave the Y coordinate as the player’s current position, and just move the X coordinate.

In essence your modifications will make the maths much simpler, since you’re only using X and Y coordinate transforms, you don’t need to use trigonometry at all.

thank u for u r kind reply .for moving target bottom to top i have already tried to change co-ordinates but i m not able to do so. If u can show me specific changes than i can understand better.
->Other thing i want to set an image as game background ,hw can i do it?

I’m afraid this moves from a basic tutorial to game development. I would suggest making a prototype of your game on the PC rather than Android to simplify development as much as possible. You can still use Cocos2D on the desktop, however to get the hang of state and logic it can be easier to make the game in a game maker. Playing around with these tools will allow you to learn very quickly how to solve the fundamental issues. You can do some very cool stuff with Game Maker in an extremely short amount of time. Alternatively Flash also allows for quick & easy development of games (and with Air can be ported to Android) – however this is more complicated than Game Maker.

The skills you learn can then be transferred to any programming language or game engine you choose to use in the future.

Is there any easy way to handle image scaling according to the pixel density of the screen? I was running the game on my device and since my screen has a high pixel density, all the sprites look smaller on the screen. Do I have to scale the sprites manually or is there any built in methods in Cocos2D to handle that?

Hi Joel. I’m not aware of a super-easy way of handling the various DPIs we get with Android. This is most likely due to the fact that games may want to scale in different ways (for example an RTS game would benefit from no scaling) and that the port we’re using of Cocos2D is largely a direct port of the iOS version which doesn’t need to worry about DPI. However, there are two solutions I have found. The first is you can scale the entire game scene, more information is available in this thread. The other is to use cocos2d-x, which when I last checked had an ongoing dialogue regarding whether to provide built-in compensation for various DPIs.

How do I re-start the background music? Because when I resume my game, only the projectile sound works.
I’ve already tried to add:
Context context = CCDirector.sharedDirector().getActivity();
SoundEngine.sharedEngine().playSound(context, R.raw.military_march, true);
in the onResume();

This is my current code:
@Override
public void onPause(){
super.onPause();

[…] just started playing around with cocos2d [a game engine] following this tutorial: How To Make A Simple Android Game with Cocos2D|Dan Clarke it was fun and easy to follow .. try it __________________ if I ever said anything that helped […]

In effect a giant sprite is the background for your scene. You can add the background sprite to the scene itself, however you’ll lose a great deal of flexibility by doing this. In the future you may want to perform some clever effects with the background that requires layering – then you’ll be glad the background is in a layer rather than the scene.

thanks for this great tutorial! What other “exotic” ways does Cocos provide for collision detection. I’m trying to create a simple game, but the collision detection causes me trouble. Somehow the game slows down, the longer i play, while using a collision detection with CGRects. Unfortunately there are not many tutorials for cocos2d on android. Same for using box2d as.

The first thing you’ll need to do is decide how the user will trigger this movement, since all taps currently result in the Shuriken being fired. I would update ccTouchesEnded to pick up whether the user has tapped with an x-coordinate of say 100 or less. If they have, instead of firing the Shuriken we trigger a ccMoveTo action to move the player sprite to the y coordinate of the touch. You’ll also need to update ccTouchesEnded to take into account the position of the player – this will involve updating the projectile.setPosition call to use the player’s y coordinate, rather than the middle of the screen. The maths afterward use the projectile’s actual position so I don’t think you’ll need to do any more.

first wanted to say, what a great tutorial! Thank you. I got your program up and running. Nice! I have a really dumb question. On the screen, why is there a changing number at the bottom left corner displayed. On your screeshot it is 60.0. I take it, it comes from fps_images.png. What is the reason behind this?

Hi Benno. The numbers are the Frames Per Second, or ‘FPS’. The FPS varies depending on the device – the screenshot in this particular example comes from Ray Wenderlich himself from (I’m assuming) the iPhone Simulator. The simulator will be using the desktop’s GPU, so a simple game like this will always run at bang-on 60fps which is the refresh rate of the monitor. Since we’re testing on an Android device, we tend to fluctuate in terms of FPS a little due to varying amounts of compute resources available to our game on a frame by frame basis.

The fps_images.png file is a ‘font map’ which allows Cocos2D to render text in a very fast manner. If you want to use your own custom fonts in a game, you’ll need to create something similar; albeit with a few more letters!

good tutorial.
but i have not understand this tutorial.
Becoz i am new on Android game development,I googled about Android Cocos2D but i have not find any beginners level tutorial or book. So plzz tell me any book or tutorial at very bigenners level to learn Android Cocos2D not iphone(Bcoz i have no idea about iphone ).

Heya!! Great tutorial, just one question (and in fact, is not to much about the tutorial, but I think you can helpeme with your cocos2d android experience). How autoescale (for different screen size) works here? Actually, I haven’t found anything about this topic in web, you wknow how is that about?? Greetings!!!

thanks Dan.initially i hated this tutorial due to lack of explanations.but later as i went through some iphone books and tried to relate both, this article was of great help in understanding the implementation.

i want to make lavels in this game.that’s mean when the users kills 30 target he will pass to the next level with differnet targets…I make another class called ‘GameLayer1″ like the “GameLayer” class but with differnet background color and different sprites but the new sprites doesn’t show up.I put these line in the “GameLayer” class in the “update(float dt)” methode
———>

You can easily add in-app purchases to any android game based on cocos2d with this open source project – http://project.soom.la.
It can be used as a reference/sample code on github or you can use it as a library/sdk.

Hi Dan, Thanks a lot for your tutorial. Can you please clarify my doubt? I am getting this error –couldn’t find class ‘org.cocos2d.opengl.CCGLSurfaceView’ referenced from the onCreate. What could be the problem? Hope you would reply me.

Hi Dan, Thank you very much for your great tutorial. I started my academic project based on this. Everything is working fine on PC. But when I set up everything in my lappy, I am running into some issues. I added jar file and “add External archive” option is not available in my eclipse and so I just selected the jar file in the libs and rightclick –> selected addtobuildpath. But I am getting errors at CGIntersect, soundengine lines in code. So, later I pasted the source code(i.e., copied org folder and pasted on ‘src’. But now to my surprise, it is showing errors on source code packages itself like on org.cocos2d etc., ). Please help me out ya. I have been trying this for a week, but no result. I have to submit this within two days. Hope you would help me out. Even I am not getting any sources online to solve this.

I’m seeing that the jar is over 2 years old. Is anyone still developing cocos2d for Android? I’ve been trying to work with it for a couple of weeks now but still can’t make the CCTMXTileMap, or CCFollow to work, and I’m not having any luck finding Android implementation of Box2D’s DebugDraw.

I’ll truly appreciate a reply to my email as this is a crucial moment in our development. We’re choosing a technology and I need to know if this will work.

hello,
i have done extacly you write but,
but when i run its does’nt show anything in emulator,
but i saw running report in ecllipse,means the activity is running
but its not show anything
can you please give me the solution what happened
i use android sdk 2.2 there

I found this tutorial extremely helpful. Thanks. I’ve been trying to port over a Cocos2d-iPhone game but as evan has asked, how do I set it up so that it’s always in portrait mode? It seems that the coordinate system is set to landscape because everything goes blank when it changes to portrait.

Following the cocos2d tutorial i m trying to make a game.After adding sprites i dnt even get the earlier output in which there is a whiote backround with character simply
player.setPosition(CGPoint.ccp(_player.getContentSize().width / 2.0f, winSize.height / 2.0f));
addChild(_player);
this line contains error