Outdated Docs > Upgrade Guides Cocos2d-x > Cocos2d-x v20 migration guide

Cocos2d-x v2.0 Migration Guide

This guide will be updated every new cocos2d-x v2.0 released.


  • contains some API changes
  • contains some new features
  • supports OpenGL ES 2.0, OpenGL ES 1.1 is no longer supported
  • supports iOS, Android and win32

Changes the same as cocos2d-iphone v20

Cocos2d-X v20 ports from cocos2d-iphone v20, so it contains the changes that cocos2d-iphone v20 makes.
So you can refer migrate_to_v2.0 for these changes

Here’s a change list of frequently used classes and interfaces
# CCTransitionRadialCW is renamed to CCTransitionProgressRadialCW
# CCTransitionRadialCCW is renamed to CCTransitionProgressRadialCCW
# ARCH_OPTIMAL_PARTICLE_SYSTEM is should be replace to CCParticleSystemQuad,
# CCParticleSystemPoint is removed in gles20 branch
# CCMenuItemImage::initFromNormalImage is renamed to initWithNormalImage
# CCDirector::setDisplayFPS(bool) is renamed to setDisplayStats(bool)
# CCAnimate::initWithDuration(ccTime duration, CCAnimation pAnimation, bool bRestoreOriginalFrame) method is removed, call CCAnimation::setDelayPerUnit instead
# CCAnimate::actionWithDuration method is removed, call CCAnimation::setDelayPerUnit instead
# CCMotionStreak::streakWithFade and initWithFade changed their params, please CCMotionStreak.h for details.
# CCLayerColor::layerWithColorWidthHeight is renamed to layerWithColor
# CCAnimation::setDelay / getDelay are renamed to setDelayPerUnit/getDelay
# CCAnimation::initWithFrames is renamed to initWithSpriteFrames
# CCAnimation::addFrame is renamed to addSpriteFrame
# CCAnimation::animationWithFrames is renamed to animationWithSpriteFrames
# CCAnimation::addFrameWithFileName > addSpriteFrameWithFileName
# CCAnimation::addFrameWithTexture
> addSpriteFrameWithTexture
# CCProgressTimer::initWithFile and initWithTexture are removed, use initWithSprite instead.
# CCProgressTimer::progressWithFile and progressWithTexture are removed, use progressWithSprite instead
# CCNode::get/setPositionInPixels, get/setAnchorPointInPixels, get/setContentSizeInPixels, boundingBoxInPixels, are remove, use the properties without “InPixel” instead
# CCParticleSystemQuad::initIndices is renamed to setupIndices
# CCDirector::isRetinaDisplay is removed
# CCRednerTexture::saveBuffer is modified to saveToFile
# bool CCSprite::isUsesBatchNode is removed, please use CCSpriteBatchNode
getSpriteBatchNode() instead, judge if the return value is NULL
# important CCSprite::spriteWithBatchNode(…) is removed, please use: sprite = CCSprite::spriteWithTexture(batchNode->getTexture(), CCRect*); batchNode->addChild(sprite); instead
# CCSprite::initWithBatchNode(…), initWithBatchNodeInPixels(…) are removed, use CCSprite::setBatchNode(…) instead
# CCSprite::displayedFrame() is renamed to displayFrame()

Cocos2d-x specific changes

Following are changes Cocos2d-X specific.

CCDictionary and CCArray

  1. Why CCMutableDictionary is Deprecated?

In gles20 branch, ‘CCMutableDictionary’ and ‘CCMutableArray’ are deprecated. You should use CCDictionary and CCArray instead.
CCDictionary is implemented by UTHash. Compared with the old CCMutableDictionary which is implemented by stl, the efficiency of the CCDictionary
is increased by at least two times. Also, CCDictionary now does not use template of cpp, so it can easily be bound to script.

  1. Key Type?

Currently, CCDictionary supports two kinds of key type, which are ‘std::stirng’ and ‘int’. One CCDictionary instance only supports one unique key type.
It is confirmed once you first invoke ‘setObject’.

  1. How to Use CCDictionary?

The way of using CCDictionary is almost the same as CCMutableDictionary. We kept the same api and removed the ‘begin’, ‘end’ and ‘next’ method which are used in
iterating the whole dictionary. Instead, we use CCDICT_FOREACH macro to achieve that. The way of using CCDICT_FOREACH is quite the same as CCARRAY_FOREACH.
The following will illustrate how to iterate CCDictionary :

      CCMutableDictionary               |                     CCDictionary   
   std::vector keys = theDict->allKeys();                  |         CCDictElement* pElement = NULL;
   std::vector::iterator it;                               |         CCDICT_FOREACH(theDict, pElement)
   for (it = keys.begin(); it != keys.end(); it++)                      |         {
   {                                                                    |            CCObjectSubClass* pSubClassObj = (CCObjectSubClass*)pElement->getObject();
        std::string oneKey = *it;                                       |            // You can also get the current key, but make sure you know the key type.
        CCObjectSubClass* pSubClassObj = theDict->objectForKey(oneKey); |            std::string oneStrKey = pElement->getStrKey(); // if the key type is string.
        // do some operation by using pSubClass pointer.                |            // int oneIntKey = pElement->getIntKey(); // if the key type is integer.
        ...                                                             |            // do some operation by using pSubClass pointer.
        ...                                                             |            ...
   }                                                                    |         }   

We kept CCDictionary::allKeys method, so you can also use the same way as CCMutableDictionary to iterate dictionary, but we strongly don’t advise you to do that.
Becasue the performance of CCDICT_FOREACH is much higher than getting all key and then using CCARRAY_FOREACH to traverse dictionary.

If you want to iterate CCDictionary at lua codes, of course, you can’t use the CCDICT_FOREACH macro, in this case, you should use the old way to make it works.

  1. Why CCMutableArray is deprecated?

In cocos2d-x 1.0.1, we have CCArray and CCMutableArray, which make users very confused,
and CCMutableArray also uses template and stl, the disadvantage is the same as CCMutableDictionary.
The old CCArray does not support reversely iterate array, we have provided the macro — CCARRAY_FOREACH_REVERSE to achieve that.

  1. Moved CCFileUtils::dictionaryWithContentsOfFile to CCDictionary::dictionaryWithContentsOfFile, added CCArray::arrayWithContentsOfFile method.


CCControlExtension in Cocos2D-X was converted to C++ by Angus C, the usage is just the same as the obj-c version. If you want to know more details, you should visit its homepage http://yannickloriot.com/2011/08/create-a-control-object-with-cocos2d-for-iphone/ .

Touch event

We have added a new method named ‘getID’ for CCTouch.
The id of CCTouch is used in MutiTouch situation, it identifies the unique name of your fingers on the screen.
You should visit MultiTouchTest in tests project for more details.

Supporting CocosBuilder

Cocos2d-X supports CocosBuilder on gles20 branch.

CCString (Added more useful methods in gles20 branch)

CCString is improved in gles20 branch

  1. More Useful Methods.

    /* static funcitons */
    /** create a string with c string 
     *  @return A CCString pointer which is an autorelease object pointer,
     *          it means that you needn't do a release operation unless you retain it.
    static CCString* stringWithCString(const char* pStr);
    /** create a string with format, it's similar with the c function 'sprintf', the default buffer size is (1024*100) bytes,
     *  if you want to change it, you should modify the kMaxStringLen macro in CCString.cpp file.
     *  @return A CCString pointer which is an autorelease object pointer,
     *          it means that you needn't do a release operation unless you retain it.
    static CCString* stringWithFormat(const char* format, ...);
    /** create a string with binary data 
     *  @return A CCString pointer which is an autorelease object pointer,
     *          it means that you needn't do a release operation unless you retain it.
    static CCString* stringWithData(unsigned char* pData, unsigned long nLen);
    /** create a string with a file, 
     *  @return A CCString pointer which is an autorelease object pointer,
     *          it means that you needn't do a release operation unless you retain it.
    static CCString* stringWithContentsOfFile(const char* pszFileName);
  2. Some Interfaces Changed

    toInt ---> intValue
    toUint ---> uintValue
    toDouble ---> doubleValue
    toFloat ---> floatValue
    toBool ---> boolValue
    getCString(new api for getting c string)

  3. Useful Macros

    define CCStringMake(str) CCString::stringWithCString(str)

    define ccs CCStringMake

These macros can construct an autorelease CCString object more easily, e.g. If we want to new a lot of CCString object, and add them into a CCArray,
the following codes will achieve that and make your code more simple.

        CCArray *stringArray = CCArray::arrayWithObjects(

CCDirector use CCLabelAtlas to show fps

If update your project from 1.1 to 2.0, you should add fps_images.png into Resources/, and add them in project configuration.

Modify some function names to make them more readable and more meaningful

All frequently used functions are marked in bold.

function name pre-modify function name after modification
CCCamera::getDirty CCCamera::isDirty
CCConfiguration::isSupportsNPOT CCConfiguration::supportsNPOT
CCConfiguration::isSupportsPVRTC CCConfiguration::supportsPVRTC
CCConfiguration::isSupportsBGRA8888 CCConfiguration::supportsBGRA8888
CCConfiguration::isSupportsDiscardFramebuffer CCConfiguration::supportsDiscardFramebuffer
CCConfiguration::isSupportsShareableVAO CCConfiguration::supportsShareableAVO
CCNode::getIsVisible CCNode::isVisible
CCNode::setIsVisible CCNode::setVisible
CCNode::getIsRunning CCNode::isRunning
CCGridBase::setIsTextureFlipped CCGridBase::setTextureFlipped
CCRGBAProtocol::getIsOpacityModifyRGB CCRGBAProtocol::isOpacityModifyRGB
CCRGBAProtocol::setIsOpacityModifyRGB CCRGBAProtocol::setOpacityModifyRGB
CCLayer::getIsTouchEnabled CCLayer::isTouchEnabled
CCLayer::setIsTouchEnabled CCLayer::setTouchEnabled
CCMenu::getIsEnabled CCMenu::isEnabled
CCMenu::setIsEnabled CCMenu::setEnabled
CCParticleSystem::getIsActive CCParticle::isActive
CCParticleSystem::getIsAutoRemovedOnFinish CCParticle::isAutoRemovedOnFinish
CCParticleSystem::setIsAutoRemovedOnFinish CCParticle::setAutoRemovedOnFinish
CCParticleSystem::getIsBlendActive CCParticleSystem::isBlendActive
CCParticleSystem::setIsBlendActive CCParticleSystem::setBlendActive
CCTexture2D::getIsHasPremultipliedAlpha CCTexture2D::hasPremultipliedAlpha
CCFileUtils::setIsPopupNotify CCFileUtils::isPopupNotify
CCFileUtils::setIsPopupNotify CCFileUtils::setPopupNotify
CCScriptSupport::getIsMultiTouches CCScriptSupport::isMultiTouches
CCScriptSupport::setIsVisible CCScriptSupport::setVisible

API changes in v2.0.2

# onEventCallback style
#* CCTouchDelegate::ccTouchesBegan/Moved/Ended/Cancelled are renamed to onTouchesBegan/Moved/Ended/Cancelled
#* CCTouchDelegate::ccTouchBegan/Moved/Ended/Cancelled are renamed to onTouchBegan/Moved/Ended/Cancelled
#* CCKeypadDelegate::keyBackClicked(), keyMenuClicked() are renamed to onKeyBackClicked(), onKeyMenuClicked()
#* CCAccelerometerDelegate::didAccelerate(…) is renamed to onAccelerometerChanged(…)
# add some convenient APIs into CCTouch
#* locationInView() is renamed to getLocationInView()
#* previousLocationInView() is renamed to CCTouch::getPreviousLocationInView()
#* add getLocation() which returns OpenGL coordinates directly
#* add getPreviousLocation() which returns OpenGL coordinates directly
#* add getDelta() which returns the delta position between the current location and previous location in OpenGL coordinates
# CCGeometry, use object-orientated functions instead of static functions
#* use p1.equals(p2) instead of CCPoint::CCPointEqualToPoint(p1, p2)
#* use s1.equals(s2) instead of CCSize::CCSizeEqualToSize(s1, s2)
#* use r.getMinX(), r.getMaxY() series instead of CCRect:CCRectGetMinX®, CCRect::CCRectGetMaxY® series
#* use r1.equals(r2) instead of CCRect::CCRectEqualsToRect(r1, r2)
#* use r1.contrainsPoint(p1) instead of CCRect::CCRectContainsPoint(r1, p1)
#* use r1.intersectsRect(r2) instead of CCRect::CCRectIntersectsRect(r1, r2)
# The param sequence of CCLabelTTF::create(label, dimension, hAlign, FontName, FontSize) is reordered CCLabelTTF::create(label, FontName, FontSize, dimension, hAlign ); to keep close with CCLabelTTF::create(label, FontName, FontSize). The param sequence is also adjusted in CCLabelTTF::initWithXxx series

Sign up for our newsletter to keep up with the latest developments, releases and updates for Cocos2d-x.