How to Make a Platformer Game with Cocos2D-X

Cocos2d-x: Why is it one of the best free game engines?

Cocos2d-x is an open-source, MIT-licensed, cross-platform game engine.

Why is it awesome? Using a single C++ codebase you can deploy games to just about every platform and since cocos2dx is open-source, you can tweak the game engine if needed.

Since good documentation can be hard to find, this book's purpose is to provide a source for clean, up-to-date cocos2d-x documentation and example source code.

The Vision: Portable Game Code

Imagine swiftly -- we're talking ninja swiftly -- striking the keys to start compiling for three platforms at once. Pretty exciting, right?

Cocos2d-x vs. Cocos2d iPhone / Swift?

Cocos2d iPhone is a also a free game engine. It differs from cocos2dx in that it is written in the Objective C programming language and only supports the iOS and Mac platforms.

If you've used Cocos2d iPhone, it's likely you enjoyed the experience. The Cocos2d API is simple and powerful. With a couple lines of code you can bring a few images and sounds to life using actions and create your own vibrant world.

Cocos2d-x takes all that beautiful API power and makes it portable using C++. It unlocks you, the developer, and enables you to choose which platforms you want to develop on and deploy to.

Why isn't Cocos2d iPhone portable?

Cocos2d iPhone isn't portable because it's written in Objective C, which isn't supported natively on some platforms, and relies heavily on Foundation Kit and Apple's Cocoa. Essentially, it's glued to the Mac/iOS platform.

While some attempts have been made to get Cocos2d iPhone compiling for Android with upgraded NDKs and open-source implementations of Foundation Kit like GNUstep or Cocotron, most of these attempts end up becoming resemblant of cocos2d-x. They even have to use some of cocos2dx's code to get things like touch input and sound effects to work.

So why not just start writing games in C++ with cocos2d-x? It's had portability in mind the whole time.

C++: A Game Dev's Best Friend

If you've been a game developer for awhile, you already know all about C++. In the game dev world, C++ is one of the most popular languages.

C++ is fast, portable, time-tested, supported natively on most platforms, has many libraries available and most programmers have some experience with it.

Recently, C++ has been updated to versions C++11 and C++14. There's a few bits of syntactic sugar that will make your programming life easier. The auto keyword, for example, is handy as a hammer in a field of nails and lambda functions are something you won't be able to live without.

C++ has been around forever, it's too useful to ever go away, it continues to get better, and it enables your app to run on the widest array of platforms. These are good reasons to choose it for your next game or app project.

The Amazon Appstore & Google Play

If you release your game solely on the Apple App Store, you could be missing out on over 50% of potential sales via the Amazon Appstore, Google Play or Steam.

Most developers want to get the full 100% of their game's potential, hence the ever-increasing popularity of the cocos2d-x cross-platform game engine.

Lua & Javascript Support

Cocos2d-X has built-in bindings for the Lua and Javascript languages, making it possible for you to script some -- if not all -- of your game code. You write the lower-level stuff in C++ and the higher-level stuff in your choice of scripting language.

The Cocos2d-X team has even released a completely Javascript-based version of Cocos2d called Cocos2D JS that combines Cocos2D-HTML5 for browsers and Cocos2D-X with Javscript bindings for mobile and desktop.

Q: How current is Cocos2d-X?

Since 2012, the Cocos2d family has been released in a coordinated fashion. Cocos2d X, Cocos2d iPhone and Cocos2d JS/HTML5 are all released simultaneously.

Q: Deploying to Windows Phone?

Thanks to a recent contribution from Microsoft, Cocos2d X now supports Windows Phone.

Q: How much platform-specific code?

You might be wondering how much platform-specific code has to be written for your game to deploy to many different platforms.

The answer is that every platform has their own project files and their own main function or app launching code. Once you get past that little bit, you're in pure Cocos2d-X C++ land, where all your game code is exactly the same.

Q: In-app purchases? Game center?

What about in-app purchases and Game Center? Well, the answer is that those things are platform-specific.

In the case of Game Center, it's easy enough to replace it with something portable like Google Play game services.

When it comes to in-app purchases, you can either go with Soomla or program store-specific in-app purchasing for the Apple App Store, Google Play and Amazon App Store individually.

Q: Android fragmentation? Multiple screens resolutions and ratios?

What about the fragmentation amongst Android devices? With so many screen resolutions and ratios, how does one write a single game code base that handles all those devices?

It's actually really easy. You just need multiple tiers of art assets and some flexible game code.

For example, you might have a sprite that is 100 pixels wide by 100 pixels tall on standard-definition devices. If that file is called "sd/Sprite.png" then you just need to output a 200x200 version called "hd/Sprite.png" and a 400x400 version called "hdr/Sprite.png", then instruct Cocos2d-X to use either the "sd", "hd" or "hdr" folder depending on the resolution.

Combine that magic with some flexible positioning of art resources on the screen based on the dimensions of the current display, and you've got a single code base that plays well and looks crisp on any device.

The alternative solution is to use Director::setDesignResolution with your highest supported resolution (for example 2048x1536) and design your graphics around that. When using setDesignResolution, Cocos2D-X will automatically scale your graphics to fit the current device's screen.

Q: Analytics? Extensions?

It's important to gather data on how your game is being played, so how do you do that in a cross-platform way?

Well, there's a Flurry plugin or this C++ Flurry Analytics wrapper. So you can start gaining insight into how your players are engaging with your game.


So there you have it. An overview of Cocos2d-X: one of the best, free, cross-platform game engines around. It's portable and it's got everything you need to start rapidly developing multi-platform games and apps.

Got questions? Leave a comment below. You can also subscribe to be notified when we release new chapters.

Next Chapter >


  1. refaelos


    Great post !!!

    For in-app purchases i would also suggest The SOOMLA Project. I’m one of the developers of this open framework for virtual economies that supports cocos2d-x and Unity3D as well as native Android and iOS.

  2. Steven

    Hi, I would like to start to write some phone game and I came across with Cocos 2D, it’s great. But I notice I have basically two ways to develop it; I could write it on C++ or javascript.

    I would like to check with are the advantages and disadvantages of written my game on each of the technologies. do you know some about it??

    Thanks in advance

    • Nat Weiss

      Hi Steven, excellent question. In general, it really depends on your type of game. If you are writing a quick little game, then Javascript can usually get the job done faster. It also has the added benefit that you can deploy to browsers. However, if you are writing a large, complex game then you might want to use C++ because you get some extra speed and stability. That’s not a very detailed answer to your question, but I hope it helps.

  3. Mark

    cocos2d is great but the issue I have is installing cocos2d-x. I’ve spent days trying to get the default project running on the android emulator. I have a game that’s done on cocos2d and want to move it cocos2d-x

    • Min

      Mark, do you have an Android device you can test on? I’d recommend getting one and using it instead of trying to get the Android emulator to work. I’ve heard of a few people using the emulator successfully, but it can be buggy. Maybe this link helps: