This quick comparison sheet gives you all the info to decide whether to use Cocos2D 1.x or Cocos2D 2.x. Contrary to most programs, a higher version number doesn’t infer “better” or “more”. There are pros and cons for both versions.

At the time of this writing the decision really only boils down to whether you want to use shaders and whether you must be able to deploy your app to 1st & 2nd generation devices. See for yourself, it’s that simple:

Cocos2D v1.x

(+) compatible with all iOS devices
(+) compatible with all libraries
(-) no OpenGL ES 2.0 shader programs

Cocos2D v2.x

(+) OpenGL ES 2.0 shader programs
(-) incompatible with armv6 CPU devices:
iPhone, iPhone 3G, iPod Touch 1G & 2G
(-) incompatible with these libraries:
Cocos3D 0.x.x, Chipmunk SpaceManager 0.1.2

All other differences to this day are minor, and most new features and bugfixes have been migrated back and forth between versions. For beginners I strongly recommend using v1.x as there’s a lot more documentation available for this version. Those who have no interest in writing shader programs can also safely use the v1.x branch without missing out.

Cocos2D 2.0 Library Compatibility Status Report

According to the Cocos3D development roadmap OpenGL ES 2.0 support will be added until version 2.0. At the moment the ETA is “2012” but since v0.9 has an ETA of “Q2 2012” it looks like Cocos3D v2.0 will not be available before Q3 2012.

I have no information about a Chipmunk SpaceManager compatibility update. However the only required fixes seem to be cpCCSprite updating its draw method (to a shader program most likely), and fixing the non-rotating sprites issue (the problem is in the CPCCNODE_FUNC_SRC macro).

How “stable” is the Cocos2D 2.0 beta?

From my experience converting the 15 Kobold2D projects with iOS & Mac targets Cocos2D 2.0 beta did not show any signs of “instability” (ie it didn’t crash or glitch for no apparent reason). Apart from the beforementioned incompatibility with Cocos3D and Chipmunk SpaceManager these are the most notable stability or compatibility issues I’ve encountered:

Frequently OpenGL errors appeared in the log but so far all of them were caused by using regular OpenGL commands in the -(void) draw method of a class. Even methods as harmless as glColor4f or glLineWidth can cause these errors to be logged!

An INVALID_OPERATION (OpenGL error 0x0502) strongly indicates the use of a OpenGL ES 1.1 command. Even though there seem to be no visual glitches you should attempt to fix these, as it is unclear if repeated/frequent OpenGL errors can get your app rejected by Apple. For your reference, here’s the list of OpenGL error codes:

If you enable ARC and try to use CCARRAY_FOREACH you will get errors because the CCARRAY_FOREACH declaration is missing a const according to Clang ARC documentation 4.3.3. Conversion of pointers to ownership-qualified types. Replace line 41 in CCArray.h to this:

Mac builds show a warning in CDXMacOSXSupport.h regarding the incorrect use of the __strong keyword with a void* pointer. Either ignore the warning, or remove the offending __strong.

The new Box2D GLES-Render code may log OpenGL errors. Since it should only be used for debugging purposes you can ignore these errors.

Note: if you use Cocos2D 2.x but have one of the incompatible armv6 devices, cocos2d still builds but quietly fails to run on your device. There is no warning or error message when attempting to debug a Cocos2D 2.x app on a armv6 device. This is not a bug, and updating the Info.plist to include the UIRequiredDeviceCapabilities keys opengles-2 and armv7 will not change that either.

Tips for migrating from Cocos2D v1.x to Cocos2D 2.x

First and most importantly: make sure your project’s Deployment Target is set to iOS 4.0 or newer. Cocos2D 2.0 is not compatible with iOS 3.x. Likewise, Cocos2D 2.0 is not compatible with Xcode 3, so make sure you upgrade to Xcode 4 regardless of whoever rants about how much Xcode 4 sucks – it’s not true: it just takes a little time to get used to and the latest 4.2 is very stable.

When upgrading from a Cocos2D v1.x project, don’t forget to add the shader files (*.fsh, *.vsh). If you forget to add the shaders, the screen remains black and GLProgram errors are logged to the console when the app initializes.

However the same black screen and GLProgram errors usually happen even if you did add the shader files. That’s because by default they’re added to the Compile Sources Build Phase, which gives you “no rule for file” warnings. Remove the .fsh and .vsh files from the Compile Sources Build Phase and add them to the Copy Bundle Resources Build Phase instead.

Tip: you only need the shader files whose filename begins with “Position”, the other shaders are not used or required by Cocos2D.

Alternatively you can use a folder reference for Shaders, because resources in a folder reference are automatically added to the Copy Bundle Resources Build Phase. This requires updating the GLProgram loader code: locate the method initWithVertexShaderFilename:fragmentShaderFilename: in GLProgram.m and instead of calling [CCFileUtils fullPathFromRelativePath:..] replace both occurrences with these lines respectively: 

Then add the following function before the initWithVertexShader.. method to allow shaders to be loaded from a “Shaders” folder reference or the subfolder “Shaders/Cocos2D” (change folder names as you please):

The tilemap property cc_vertexz is not supported by Cocos2D 2.0 beta but will be back in beta 2. In particular those who use isometric tilemaps will want to wait for the release of Cocos2D 2.0 beta 2.

CCDirector no longer supports “director types”. CCDirectorDisplayLink is used by default. All references to other director types need to be removed.

CCDirector no longer supports device orientation. All autorotation and device orientation is handled by RootViewController now. Fortunately, [[UIDevice currentDevice] orientation] can be used in place of [[CCDirector sharedDirector] deviceOrientation]. The enums are the same, except that they begin with UI instead of CC.

Forcing a specific orientation is a simple matter of returning YES only to the desired orientation in the RootViewController method shouldAutorotateToInterfaceOrientation.

Don’t forget to add the fps-images-hd.png file to your project’s resources. Otherwise the fps counter will be garbled on Retina devices.

If you’re using Box2D, you will need to replace your version of the GLES-Render class with the one from the Cocos2D Box2D project template. Then change your draw method to use the OpenGL ES 2.0 compatible drawing code:

Change the opengles-1 UIRequiredDeviceCapabilities key in your Info.plist to opengles-2 and optionally add armv7 as well. If you don’t change to opengles-2 your app will be rejected by Apple because iTunes would assume your app to be compatible with armv6 devices, which it isn’t.

Under Build Settings remove all references to the armv6 architecture, so that only armv7 remains. This is not strictly necessary but might reduce the size of your app.

Other than that, expect some build errors due to the changes in the Cocos2D API. That’s the things you need to fix in your code, and those changes may range from trivial to extensive changes with undesired side effects. Unfortunately it’s hard to say up front which scenario you’ll be facing.

What about ARC (automatic reference counting)?

Both Cocos2D v1.1 and v2.0 are supposedly compatible with ARC, but they do not support ARC out of the box. Enabling Objective-C Automatic Reference Counting in the Build Settings of a newly create Cocos2D project template leads to 700+ compile errors. Don’t even attempt to try to fix them, that won’t work, not even with the help of the Xcode function Refactor -> Convert to Objective-C ARC.

The trick here is to put all of the Cocos2D source code in a static library target with ARC disabled, and only enable ARC for your actual app and also link the app’s target with the static library.

Going forward the problem for Cocos2D will be to update the Xcode project templates to add such a static library – but according to my extensive research on the Xcode 4 project template format adding a static library to an Xcode project template isn’t even possible. So in all likelihood enabling ARC for Cocos2D based apps will remain a manual process.

Unless of course you use Cocos2D by installing Kobold2D. Kobold2D has ARC enabled for all of its template projects by default. No fuss, it just works.

This article was brought to you by ...

I very much enjoy the learning process, the pushing of boundaries (mine and yours and that of technology), having the freedom to pursue whatever is on my mind, to boldly program what no one has programmed before, and to write about what I've learned. Help me help you by browsing the products in the Learn Cocos2D Store.

9 Responses to “Choosing between Cocos2D v1.x & 2.x and Tips for updating to Cocos2D 2.0”

  1. […] from […]

  2. Clops says:

    It seems as though SneakyInput is also incompatible with cocos2d v1.1 and above, which is a shame :(

  3. Andrew says:

    Does Chipmunk play well with Cocos2D 2.0 and Kobold2D? If so, what, where how to set it up?

  4. David Dunham says:

    Kobold2D is still 1.x only though, right?

    • Yes, because cocos2d 2.x was still changing a lot up until a few days ago. I have the current release candidate working with Kobold2D and will release Kobold2D 2.0 soon.

  5. luke says:

    thank you very much for expelling. i think I’m going to stick to v1 for now

    kind regards

  6. JC says:

    Hi Ray
    I’m converting cocos2d 1.x projects to cocos2d 3.0 projects. Is there a quick and easy way to get them to compile in Xcode. It’s been awhile since I did any cocos2d.