Outdated Docs > Upgrade Guides Cocos2d-x > API Change List from v1x to 2x

API Change List from v1.x to 2.x

1. New API Concepts

Following the Cocos2d Javascript API, we applied the most part of API changes back to C++. Here’re some basic concepts of these modifications

1.1 Static Constructors

  • [v2.0] Use Classname::create instead of Classname::ClassnameWithResource. Please refer to About Static Constructor API changes in cocos2d-x v2.0. Lua API set and Javascript API set are also benefited from this clear style.
  • [v2.0] use createWithResource to avoid conflicts
  • [v2.0] the CCObject* returned from ::create() methods are always a auto-release object.

1.2 Singletons

  • [v2.0.1] Singletons have unified static constructors Singleton::getInstance() and destructor Singleton::destroyInstance() instead of the old style `Classname::sharedClassname. This modification is also applied in lua and javascript bindings.

    h2. 1.3 Event Callbacks

    • [v2.0.1] Event callbacks, e.g. CCTouchDelegate::ccTouchesBegan/Moved/Ended/Cancelled(), are renamed to CCSomethingDelegate::onSomethingDone(), including ** Standard touch delegate: `onTouchesBegan/Moved/Ended/Cancelled@
    • Targeted touch delegate: onTouchBegan/Moved/Ended/Cancelled
    • Keypad delegate: onKeyBackClicked, onKeyMenuClicked
    • G-Sensor delegate: onAccelerometerChanged

2. Data structure: CCDictionary and CCArray

2.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.

2.2 Key Type of CCDictionary

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’.

2.3 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.

2.4 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.

3. Classname::isStatus to require a bool property

For bool properties:
* The getter functions are unified from getIsBool() or getBool() to isBool().
* The setter functions are unified from setIsBool(value) to setBool(value)

All frequently used functions are marked in bold.

function name before function name in v2.x
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

4. Classes


  • [v2.0-sync] CCDirector::setDisplayFPS(bool) > setDisplayStats(bool). Now the stats show 3 numbers: *** The top one shows how many times of OpenGL draw functions are called per frame, *** the middle one shows the second consumed per frame , *** and the bottom one is the FPS that we all familiar with. ** CCDirector::isRetinaDisplay() is removed * **Add fps_images.png into your Resources/, and add them into project configuration. Now CCDirector uses CCLabelAtlas to show FPS, do this to highly improve the performance on android. h2. CCActionManager, CCTouchDispatcher, CCScheduler ** CCActionManager, CCTouchDispatcher, CCScheduler are member variables of CCDirector. But singletons with the ‘cache’ types, e.g. CCTextureCache, CCAnimationCache, CCShaderCache are still there. h2. Sprite * CCSprite::displayedFrame()> displayFrame()


*** CCSprite::spriteWithBatchNode(...) is removed, please use: sprite = CCSprite::spriteWithTexture(batchNode->getTexture(), CCRect*); batchNode->addChild(sprite); instead
*** [v2.0-sync] CCSprite::initWithBatchNode(...), initWithBatchNodeInPixels(...) are removed, use CCSprite::setBatchNode(...) instead
*** bool CCSprite::isUsesBatchNode() is removed, please use CCSpriteBatchNode* getSpriteBatchNode() instead, judge if the return value is NULL
*** Sample code of creating a sprite with batch node

// create batch node from image file
CCSpriteBatchNode* batch = CCSpriteBatchNode::create("BatchNodeTexture.png");
// get the texture in batch node
CCTexture2D* texture = batch->getTexture();
// create sprite from this texture
CCSprite* sprite = CCSprite::createWithTexture(texture, CCRectMake(0,0,32,32));
// organize the child relation

CCGeometry, CCPoint, CCSize, CCRect

Use object-orientated functions instead of static functions
* [v2.0.2] use p1.equals(p2) instead of CCPoint::CCPointEqualToPoint(p1, p2)
* [v2.0.2] use s1.equals(s2) instead of CCSize::CCSizeEqualToSize(s1, s2)
* [v2.0.2] use r.getMinX(), r.getMaxY() series instead of CCRect:CCRectGetMinX®, CCRect::CCRectGetMaxY® series
* [v2.0.2] use r1.equals(r2) instead of CCRect::CCRectEqualsToRect(r1, r2)
* [v2.0.2] use r1.contrainsPoint(p1) instead of CCRect::CCRectContainsPoint(r1, p1)
* [v2.0.2] use r1.intersectsRect(r2) instead of CCRect::CCRectIntersectsRect(r1, r2)


Some convenient APIs are added into CCTouch
* [v2.0.2] locationInView() is renamed to getLocationInView()
* [v2.0.2] previousLocationInView() is renamed to CCTouch::getPreviousLocationInView()
* [v2.0.2] add getLocation() which returns OpenGL coordinates directly
* [v2.0.2] add getPreviousLocation() which returns OpenGL coordinates directly
* [v2.0.2] add getDelta() which returns the delta position between the current location and previous location in OpenGL coordinates


  • [v2.0-sync] CCTransitionRadialCW > CCTransitionProgressRadialCW * CCTransitionRadialCCW> CCTransitionProgressRadialCCW

Particle System

  • [v2.0-sync] ARCH_OPTIMAL_PARTICLE_SYSTEM > CCParticleSystemQuad, * CCParticleSystemQuad::initIndices> setupIndices()
  • [v2.0] CCParticleSystemPoint is removed, please use CCParticleSystemQuad instead.


  • [v2.0] CCMenuItemImage::initFromNormalImage > initWithNormalImage h2. Animate * CCAnimate::initWithDuration(ccTime duration, CCAnimation *pAnimation, bool bRestoreOriginalFrame) method is removed, call CCAnimation::setDelayPerUnit(float) instead * CCAnimate::actionWithDuration(ccTime duration, CCAnimation *pAnimation, bool bRestoreOriginalFrame) method is removed, call CCAnimation::setDelayPerUnit(float) instead h2. MontionStreak * CCMotionStreak::streakWithFade and initWithFade changed their params, please look CCMotionStreak.h for details. h2. Layer * CCLayerColor::layerWithColorWidthHeight is renamed to layerWithColor h2. Animation * 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
  • [v2.0-sync] CCAnimation::addFrameWithTexture -> addSpriteFrameWithTexture


  • [v2.0-sync] CCProgressTimer::initWithFile(char**) and initWithTexture are removed, use initWithSprite instead. ** [v2.0-sync] CCProgressTimer::progressWithFile and progressWithTexture are removed, use progressWithSprite instead


  • [v2.0-sync] CCNode::get/setPositionInPixels, get/setAnchorPointInPixels, get/setContentSizeInPixels, boundingBoxInPixels(), are remove, use the properties without “InPixel” instead


  • [v2.0] CCRenderTexture::saveBuffer(…) is modified to saveToFile(…)


  • [v2.0] CCFileUtils::dictionaryWithContentsOfFile is moved to CCDictionary::createWithContentsOfFile, added CCArray::createWithContentsOfFile method.


  1. More Useful Methods.

    /** create a string with std string, you can also pass a c string pointer because the default constuctor of std::string can access a c string pointer. 
     *  @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* create(const std::string& str);
    /** 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* createWithFormat(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* createWithData(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* createWithContentsOfFile(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. Helper Marcos

    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(

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