For this tutorial post we assume you are already familiar with Cocos2d 2.x. We will point out the important changes that come with the new version of Cocos and give example implementations based on what you already know from Cocos2d 2.x.

CCNodes, CCScenes and CCLayers

CCLayer does not exist anymore. CCLayer used to be the class you used for scenes with user interaction. In Cocos2d 3.x any CCNode can handle touch input. CCNode is the new CCLayer. For scenes use CCScene for everything in your scene use CCNode.

Touch handling

We will soon come up with a complete tutorial on touch handling in Cocos2d 3.0. For now it is most important to know how:

  • to enable touch handling on you CCNode:

    self.userInteractionEnabled = TRUE;
  • to catch a touch and its touch position:

    - (void)touchBegan:(UITouch *)touch withEvent:(UIEvent *)event
         CGPoint touchLocation = [touch locationInNode:self]; 
         // put your touch handling code here
  • And to know the three other methods that can be implemented to determine moving, ending, or canceled touches:

    - (void)touchMoved:(UITouch *)touch withEvent:(UIEvent *)event
    - (void)touchEnded:(UITouch *)touch withEvent:(UIEvent *)event
    - (void)touchCancelled:(UITouch *)touch withEvent:(UIEvent *)event

Note for Cocos2D 3.3

If you are using Cocos2D 3.3+ (it's part of SpriteBuilder 1.3+) you will have to replace all occurrences of UITouch and UITouchEvent with CCTouch and CCTouchEvent, respectively. You can find more information as part of the SpriteBuilder update guide.

Good bye CCMenu! Hello CCLayout!

In the past CCMenu was the easiest way to create a menu. Since CCMenu was the only class that provided handy layout methods (alignItemsVertically, etc.) the class was often used to layout a lot of other things, not only menus. Cocos2d 3.0 solves this issue by providing a CCLayout class. This class can layout any kind of CCNode, which makes layouting our scenes a charm. If you want to build a menu in Cocos2d 3.0 you will use a CCLayout container and simply add CCButtons to it. This is an example from a simple layout:

// create first button
self.calculationStepButton = [CCButton buttonWithTitle:LABEL_STEP];
[self.calculationStepButton setTarget:self selector:@selector(calculationStepButtonTouched:)];
// create second button
self.animationButton = [CCButton buttonWithTitle:LABEL_ANIMATE];
[self.animationButton setTarget:self selector:@selector(animateButtonTouched:)];
// setup layoutbox and add items
CCLayoutBox *layoutBox = [[CCLayoutBox alloc] init];
layoutBox.anchorPoint = ccp(0.5, 0.5);
[layoutBox addChild:self.calculationStepButton];
[layoutBox addChild:self.animationButton];
layoutBox.spacing = 10.f;
layoutBox.direction = CCLayoutBoxDirectionVertical;
[layoutBox layout];
layoutBox.position = ccp(CANVAS_SIZE.width + (self.contentSize.width - CANVAS_SIZE.width)/2, self.contentSize.height/2);
[self addChild:layoutBox];

Implementing a custom update Method

In Cocos2d 2.x you needed two steps in order to implement an update method that is called every frame:

// 1) schedule update 
[self scheduleUpdate]; 
// 2) override update method
- (void) update:(ccTime)delta 

In Cocos 2d 3.x you do not need to call scheduleUpdate anymore. Instead you only override this method in any CCNode subclass:

- (void)update:(CCTime)delta {

Resource management

If you don't plan on using SpriteBuilder, you can continue to use suffixes to manage images of different resolutions.

First, you need to comment out [CCBReader configureCCFileUtils] in AppDelegate.m. After that, the following suffixes should work:

  • no suffix, non-retina iPhone
  • "-hd", retina iPhone
  • "-iphone5hd", iPhone 5+
  • "-ipad", non-retina iPad
  • "-ipadhd", retina iPad
  • "-iphone5", non-retina assets used for iPhone 5+ if no "-iphone5hd"

There's more to come!

In the coming days and weeks we will be adding many tutorials on new Cocos2d 3.0 APIs, so stay tuned.

If you're missing any instructions for Cocos2d 3.0 please shoot me an E-Mail:


If you have feedback on this tutorial or find any mistakes, please open issues on the GitHub Repository or comment below.

Summer academy

An iOS Development Summer Course

Design, code and launch your own app. Locations in San Francisco and Asia

Find your location

Product College

A computer science college

Graduate into a successful career as a founder or software engineer.

Learn more

Cookies on Make School's website

We have placed cookies on your device to ensure that we give you the best experience on our website.

This site uses cookies to deliver our services. By using our site, you acknowledge that you have read and understand our Cookie Policy, Privacy Policy, and our Terms of Service. Your use of Make School’s Products and Services is subject to these policies and terms.

Please note that Make School no longer supports Internet Explorer

We recommend upgrading to a modern web browser. Learn more