IMPORTANT: This guide is a WIP. It will be updated with every new cocos2d v2.0 release.

This guide ONLY shows how to migrate your cocos2d v1.0 game to cocos2d v2.0-beta2.

• It DOES NOT explain how to migrate from v2.0-alpha to v2.0-beta2.
• It DOES NOT explain new features.

cocos2d v2.0:

• contains some API changes
• contains some new features
• iOS: Supports OpenGL ES 2.0. OpenGL ES 1.1 is no longer supported
• iOS: Only works on iOS >= 4.0
• Mac: Only works on OS X >= 10.6
• LLVM is the only supported compiler

Only OpenGL ES 2.0 devices are supported:

• iPhone and iPhone 3G are NO LONGER supported.
• iPad 1, iPad 2, iPad 3, iPhone 3GS, iPhone 4, iPhone 4S, iPod Touch 3 and iPod Touch 4 ARE supported

• Xcode 3.x is NO LONGER supported. Use Xcode 4 or newer
• gcc / llmv-gcc are NO LONGER supported. Use LLVM 3.0 or newer

blocks are used internally, so:

• iOS 3.x and Mac OS X 10.5 are NO LONGER supported
• Only iOS 4.0 / Mac OS X 10.6 and newer are supported

1. Download and unzip the latest cocos2d 2.0 version (http://www.cocos2d-iphone.org/download)
2. Replace your old cocos2d source files with the new ones

     $ cd ~/my_game/libs/
     $ rm -rf cocos2d
     $ cp -R ~/src/cocos2d-iphone-2.0/cocos2d .

3. Update the fps_images*.png files

     $ cd ~/my_game/Resources
     $ cp ~/src/cocos2d-iphone-2.0/Resources/Fonts/fps_images* .

4. Remove cocos2d references from Xcode
   1. Xcode → View → Navigators → Show Project Navigator (or Command 1)
   2. Select cocos2d sources
   3. Press the Delete key
   4. Select Remove references only
5. Re-add the cocos2d references
   1. On the Project Navigator view select the libs folder
   2. Right-click on it and select Add Files to My Game
   3. Select the cocos2d folder and add it

1. Download and unzip the latest cocos2d 2.0 version (http://www.cocos2d-iphone.org/download)
2. Install the templates

     $ cd ~/src/cocos2d-iphone-2.0/
     $ ./install-templates.sh -f

3. Xcode → File → New Project → select the cocos2d v2.0 template
4. Copy all your game sources / resources to the newly created template

Many API were renamed, added and/or deleted. cocos2d has backward-compatibility mode enabled by default. That means that most of v1.0 code will compile and run with v2.0, but it might raise many compiler warnings.

In order to disable backward compatibility, edit ccConfig.h file, and change

#define CC_ENABLE_DEPRECATED 0  // Disables Deprecated code. Enabled by default.

Although most of the v1.0 features are present on v2.0, some of them are not present on v2.0, even when “Backward compatibility” mode is enabled.

The following are the methods / classes that are not part of the backward-compatibiliy set, and the user is responsible for using them correctly.

// Set Director type
// 1.0: 
+(BOOL) setDirectorType:(ccDirectorType) directorType;
 
// v2.0: 
// No longer needed. DisplayLink is the only supported director

// Interface orientation
// 1.0:
-(void) setDeviceOrientation:(ccDeviceOrientation)orientation;
 
// v2.0: set the director delegate, and set shouldAutorotateToInterfaceOrientation
{ 
   [director setDelegate:self];
}
- (BOOL)shouldAutorotateToInterfaceOrientation:(UIInterfaceOrientation)interfaceOrientation
{
    return UIInterfaceOrientationIsLandscape(interfaceOrientation);
}

// Running the Director
// 1.0:
-(void) runWithScene:(CCScene*)scene;
 
// v2.0:
// On iOS, the Director will be animated (run) automatically when the view is displayed
// so, there is no need to "run" the director. By just pushing the scene is enough.
// The Director will raise an Assert if you try to run it twice
-(void) pushScene:(CCScene*)scene;
 
// On Mac, the Director, for the moment, is not animated (run) automatically, so you still have to use call [director startAnimation] after pushing the scene
-(void) pushScene:(CCScene*)scene;
-(void) startAnimation;  // Mac only since Animation is not started automatically on Mac.

view, setView should be used instead of openGLView / setOpenGLView. Related to this change, is that on iOS, CCDirector is a subclass of UIViewController.

//v1.0
@property (nonatomic,readwrite,retain) CC_GLVIEW *openGLView;
 
// v2.0
@property(nonatomic, retain) CCGLView *view;

CCActionManager, CCScheduler, CCTouchDispathcer (iOS) and CCEventDispatcher (Mac) are NO LONGER singletons. Instead, they are properties of CCDirector.

// v1.0
+ (CCTouchDispatcher*) sharedDispatcher; // CCTouchDispatcher class method
+ (CCScheduler*) sharedScheduler;        // CCScheduler class method
+ (CCActionManager *) sharedManager;     // CCActionManager class method
 
 
// v2.0
@property (nonatomic,readwrite,retain) CCScheduler *scheduler;   // CCDirector property
@property (nonatomic,readwrite,retain) CCActionManager *actionManager;  // CCDirector property
@property (nonatomic,readwrite,retain) CCTouchDispatcher * touchDispatcher; // CCDirector property (iOS)
@property (nonatomic, readwrite, retain) CCEventDispatcher* eventDispatcher; // CCDirector property (Mac)

// v1.0
@interface EAGLView : UIView         // iOS
@interface MacGLView : NSOpenGLView  // Mac
 
// v2.0
@interface CCGLView : UIView         // iOS
@interface CCGLView : NSOpenGLView   // Mac

It is safe to replace all occurrences of EAGLView / MacGLView with CCGLView

1. Search for EAGLView on your iOS project (an occurrence might appear on the AppDelegate file)
2. Search for MacGLView on your Mac project (an occurrence shall appear on the main.m file)

On Mac, you will also need to edit the MainMenu.xib

1. Xcode → View → Navigators → Show Project Navigator
2. Resources → English.proj → MainMenu.xib
3. Select the MacGLView
4. Go to Identity Inspector → Custom Class → Class
5. Change MacGLView to CCGLView

IMPORTANT: on cocos2d v2.0, if you call [item removeWithCleanup:YES], its callback is going to be cleaned-up.

Added fileName / texture to API. Uses color3B instead of color4B. CCRibbon (a class used by CCMotionStreak) was removed in v2.0.

// v1.0
+(id)streakWithFade:(float)fade minSeg:(float)seg image:(NSString*)path width:(float)width length:(float)length color:(ccColor4B)color;
-(id)initWithFade:(float)fade minSeg:(float)seg image:(NSString*)path width:(float)width length:(float)length color:(ccColor4B)color;
 
// v2.0
+ (id) streakWithFade:(float)fade minSeg:(float)minSeg width:(float)stroke color:(ccColor3B)color textureFilename:(NSString*)path;
+ (id) streakWithFade:(float)fade minSeg:(float)minSeg width:(float)stroke color:(ccColor3B)color texture:(CCTexture2D*)texture;
- (id) initWithFade:(float)fade minSeg:(float)minSeg width:(float)stroke color:(ccColor3B)color textureFilename:(NSString*)path;
- (id) initWithFade:(float)fade minSeg:(float)minSeg width:(float)stroke color:(ccColor3B)color texture:(CCTexture2D*)texture;

CCParticleSystemPoint is no longer supported. Use CCParticleSystemQuad instead.

// v1.0
@interface CCParticleSystemPoint : CCParticleSystem
 
// v2.0
// No longer supported. Use CCParticleSystemQuad instead

API uses CCSprite instead of filename / texture

// v1.0
+ (id) progressWithFile:(NSString*) filename;
- (id) initWithFile:(NSString*) filename;
+ (id) progressWithTexture:(CCTexture2D*) texture;
- (id) initWithTexture:(CCTexture2D*) texture;
 
// v2.0
+ (id) progressWithSprite:(CCSprite*) sprite;
- (id) initWithSprite:(CCSprite*) sprite;

Cocos2D 2.0 uses Objective-C blocks internally now, so extra caution should be used when calling some methods such as the following one:

-(void) removeFromParentAndCleanup:(BOOL)cleanup;

Setting the cleanup flag to YES might cause side-effects in your application's logic which is still making implicit references to freed resources. CCMenuItems, which use blocks internally to launch actions, might be giving problems and not launching an action, assuming you have removed the item from its parent node with the cleanup flag activated and added it back, is one of the telling signs. Simply changing the flag to NO should be enough.

The -(BOOL)usesBatchNodes method is not available anymore. As a replacement, you can use the following CCSprite public property treating the return value as a boolean value (Objective-C will treat nil as NO, any other value as YES):

Also, CC_HONOR_PARENT_TRANSFORM flags are no longer supported.

// v1.0
-(void) useSelfRender;
@property (nonatomic,readwrite) BOOL usesBatchNode;
@property (nonatomic,readwrite,assign) CCSpriteBatchNode *batchNode;
 
// v2.0
@property (nonatomic,readwrite,assign) CCSpriteBatchNode *batchNode;

// v1.0
sprite1 = [CCSprite spriteWithBatchNode:batch rect:CGRectMake(...)];
sprite2 = [[CCSprite alloc] initWithBatchNode:batch rect:CGRectMake(...)];

// v2.0
// initWithBatchNode / spriteWithBatchNode were removed in order to simply the API
sprite1 = [CCSprite spriteWithTexture:batch.texture rect:CGRectMake(...)];
sprite2 = [[CCSprite alloc] initWithTexture:batch.texture rect:CGRectMake(...)];

// v1.0
@property (nonatomic,readwrite) ccHonorParentTransform honorParentTransform;
 
// v2.0
// This feature is, for the moment, not supported. It might be re-added in the future.

You must attach the batch node to an existing CCNode. It cannot be used as root node anymore or it will trigger the following assertion in the CCSpriteBatchNode's -visit method.

NSAssert(parent_ != nil, @"CCSpriteBatchNode should NOT be root node");

CCTransitionRadialCW and CCTransitionRadialCCW were renamed to CCTransitionProgressRadialCW and CCTransitionProgressRadialCCW respectively.

// v1.0
@interface CCTransitionRadialCW : CCTransitionProgress
@interface CCTransitionRadialCCW : CCTransitionProgress
 
// v2.0
@interface CCTransitionProgressRadialCW : CCTransitionProgress
@interface CCTransitionProgressRadialCCW : CCTransitionProgress

If are not using any custom CCNode # draw in your game, then you are Ok and you won't have to migrate your code to OpenGL ES 2.0.

But if you have have custom CCNode # draw code, then you will have to migrate it to v2.0.

CCSprite cocos2d v1.0 code

-(void) draw
{
	[super draw];
 
	// Default GL states: GL_TEXTURE_2D, GL_VERTEX_ARRAY, GL_COLOR_ARRAY, GL_TEXTURE_COORD_ARRAY
	// Needed states: GL_TEXTURE_2D, GL_VERTEX_ARRAY, GL_COLOR_ARRAY, GL_TEXTURE_COORD_ARRAY
	// Unneeded states: -
 
	BOOL newBlend = blendFunc_.src != CC_BLEND_SRC || blendFunc_.dst != CC_BLEND_DST;
	if( newBlend )
		glBlendFunc( blendFunc_.src, blendFunc_.dst );
 
#define kQuadSize sizeof(quad_.bl)
	glBindTexture(GL_TEXTURE_2D, [texture_ name]);
 
	long offset = (long)&quad_;
 
	// vertex
	NSInteger diff = offsetof( ccV3F_C4B_T2F, vertices);
	glVertexPointer(3, GL_FLOAT, kQuadSize, (void*) (offset + diff) );
 
	// color
	diff = offsetof( ccV3F_C4B_T2F, colors);
	glColorPointer(4, GL_UNSIGNED_BYTE, kQuadSize, (void*)(offset + diff));
 
	// tex coords
	diff = offsetof( ccV3F_C4B_T2F, texCoords);
	glTexCoordPointer(2, GL_FLOAT, kQuadSize, (void*)(offset + diff));
 
	glDrawArrays(GL_TRIANGLE_STRIP, 0, 4);
 
	if( newBlend )
		glBlendFunc(CC_BLEND_SRC, CC_BLEND_DST);
}

CCSprite cocos2d v2.0 code

-(void) draw
{
	CC_NODE_DRAW_SETUP();
 
	ccGLBlendFunc( blendFunc_.src, blendFunc_.dst );
 
	ccGLBindTexture2D( [texture_ name] );
 
	//
	// Attributes
	//
 
	ccGLEnableVertexAttribs( kCCVertexAttribFlag_PosColorTex );
 
#define kQuadSize sizeof(quad_.bl)
	long offset = (long)&quad_;
 
	// vertex
	NSInteger diff = offsetof( ccV3F_C4B_T2F, vertices);
	glVertexAttribPointer(kCCVertexAttrib_Position, 3, GL_FLOAT, GL_FALSE, kQuadSize, (void*) (offset + diff));
 
	// texCoods
	diff = offsetof( ccV3F_C4B_T2F, texCoords);
	glVertexAttribPointer(kCCVertexAttrib_TexCoords, 2, GL_FLOAT, GL_FALSE, kQuadSize, (void*)(offset + diff));
 
	// color
	diff = offsetof( ccV3F_C4B_T2F, colors);
	glVertexAttribPointer(kCCVertexAttrib_Color, 4, GL_UNSIGNED_BYTE, GL_TRUE, kQuadSize, (void*)(offset + diff));
 
 
	glDrawArrays(GL_TRIANGLE_STRIP, 0, 4);
 
}

cocos2d v1.0: you had to restore the GL state to the default one.

	// eg: CCLayerColor
 
	// Default GL states: GL_TEXTURE_2D, GL_VERTEX_ARRAY, GL_COLOR_ARRAY, GL_TEXTURE_COORD_ARRAY
	// Needed states: GL_VERTEX_ARRAY, GL_COLOR_ARRAY
	// Unneeded states: GL_TEXTURE_2D, GL_TEXTURE_COORD_ARRAY
	glDisableClientState(GL_TEXTURE_COORD_ARRAY);
	glDisable(GL_TEXTURE_2D);
 
	[...]
 
	// restore default GL state
	glEnableClientState(GL_TEXTURE_COORD_ARRAY);
	glEnable(GL_TEXTURE_2D);

cocos2d v2.0: Uses the cocos2d GL state cache

	// eg: CCLayerColor
 
	// In cocos2d v2.0 there is not need to enable / disable the texture
	ccGLEnableVertexAttribs( kCCVertexAttribFlag_Position | kCCVertexAttribFlag_Color );

cocos2d 1.0: Call GL API directly

	// update new blending
	BOOL newBlend = blendFunc_.src != CC_BLEND_SRC || blendFunc_.dst != CC_BLEND_DST;
	if( newBlend )
		glBlendFunc( blendFunc_.src, blendFunc_.dst );
 
	[...]
 
	// restore default blending
	if( newBlend )
		glBlendFunc(CC_BLEND_SRC, CC_BLEND_DST);

cocos2d v2.0: Uses the cocos2d GL state cache

	ccGLBlendFunc( blendFunc_.src, blendFunc_.dst );

cocos2d 1.0: Call GL API directly

	// binding
	glBindTexture(GL_TEXTURE_2D, [texture_ name]);
 
	// deleting
	int textureID = [texture_ name];
	glDeleteTextures(1, &textureId )

cocos2d v2.0: Uses the cocos2d GL state cache

	// binding
	ccGLBindTexture2D( [texture_ name] );
 
	// deleting
	ccGLDeleteTexture( [texture_ name] );

cocos2d v1.0: Uses OpenGL ES 1.1 code

cocos2d v2.0: Uses OpenGL ES 2.0 code. For further info about GL ES 2.0, please read OpenGL ES 2.0 Programming Guide

XXX TODO XXX Explain how to support RetinaDisplay with the new cocos2d v2.0 code

Since May 2011, the official cocosLive server is no longer accepting new games. So cocosLive and its dependency TouchJSON are no longer included in cocos2d.

But in case you want to create your own cocosLive server, you should read the following instructions:

• http://thebackfiregames.wordpress.com/2011/05/13/creating-your-own-personal-score-server/

If you are going to use cocosLive, you should include TouchJSON and cocosLive (copy them from cocos2d-iphone v1.0) in your project

FontLabel is no longer supported. If you want to use custom TTF fonts in your project, you should add them in your .plist file.

Example:

• http://tetontech.wordpress.com/2010/09/03/using-custom-fonts-in-your-ios-application/