How to migrate a cocos2d v0.8.x project to v0.99

Testing your code with v0.8.2

Before using cocos2d v0.99, you should test your code with the latest version of v0.8.x.

• Install cocos2d v0.8.2 (latest v0.8. version)
• Compile everything
• Update your code so that it doesn't use deprecated methods and/or interfaces

Installing v0.99

Once you have tested that your game runs without warnings using v0.8.2, you can replace cocos2d v0.8.2 with cocos2d v0.99.0.

Steps to replace it:

• Open your game XCode project
• From XCode remove the cocos2d folder: delete the references also moving them to the trash folder
• download cocos2d v0.99 (latest v0.99 version)
• copy the v0.99 cocos2d directory to your game directory
• From XCode, include the recently copied cocos2d directory

Enabling compatibility

Once you have installed cocos2d v0.99, you should enable compatibility with v0.8.

Steps to enable compatibility:

• edit the file cocos2d/ccConfig.h
• uncomment the line: #define CC_COMPATIBILITY_WITH_0_8 1

// the following line should be uncommented


#define CC_COMPATIBILITY_WITH_0_8 1

If Compatiblity mode is enabled, then for each new v0.9 class, an old v0.8 class will be added as a subclass of the new one.

eg:

// if v0.8 compatiblity mode is enabled, then this code will be added


 

__attribute__(
(
deprecated)
)


@interface
 Sprite :
 CCSprite

@end


 

__attribute__(
(
deprecated)
)


@interface
 Director :
 CCDirector

@end


 

// etc... etc.. etc..

IMPORTANT : It is recommended to disable compatibility with v0.8 once your project compiles OK with v0.9.

Updating your code

Once compatibility is enabled, you can compile your project. You will find several warnings and errors, but don't panic.

Adding namespaces

v0.99 classes have the CC prefix. This prefix was added in order to prevent collision with other possible libraries or user code. So, it is safe to assume that:

• Classes that start with CC belong to cocos2d.
• Classes that don't start with CC don't belong to cocos2d

Example:

// v0.8.x classes


Sprite *
sprite =
 [
Sprite sprite....]
;

Director *
director =
 [
Director sharedDirector]
;

Scene *
scene =
 [
Scene ...]
;

Layer *
layer =
 [
Layer ...]
;

 

// 0.99.0 classes


CCSprite *
sprite =
 [
CCSprite sprite....]
;

CCDirector *
director =
 [
CCDirector sharedDirector]
;

CCScene *
scene =
 [
CCScene ...]
;

CCLayer *
layer =
 [
CCLayer ...]
;

There are some exceptions :

• The CocosNode class was renamed to CCNode
• The TextureMgr class was renamed to CCTextureCache

Updating Sprites

In v0.99 AtlasSprite and Sprite were merged in one single class: CCSprite .

New classes:

• Sprite → CCSprite
• AtlasSprite → CCSprite
• AtlasSpriteFrame → CCSpriteFrame
• SpriteFrame → CCSpriteFrame
• Animation → CCAnimation
• AtlasAnimation → CCAnimation
• AtlasSpriteManager → CCSpriteSheet ← NEW NAME

Example:

// v0.8 code: Atlas Sprites


AtlasSpriteManager *
mgr =
 [
AtlasSpriteManager spriteManager...]
;

AtlasSprite *
sprite =
 [
mgr createSpriteWith...]
;

[
mgr addChild:
sprite]
;

 

// v0.99 code


CCSpriteSheet *
sheet =
 [
CCSpriteSheet spriteSheet...]
;

CCSprite *
sprite =
 [
CCSprite spriteWithSpriteSheet...]
;

[
sheet addChild:
sprite]
;

 

// v0.8 code: Sprites


Sprite *
sprite =
 [
Sprite spriteWith...]
;

[
self addChild:
sprite]
;

 

// v0.99 code


CCSprite *
sprite =
 [
CCSprite spriteWith...]
;

[
self addChild:
sprite]
;

As you can see, CCSprite can be used as a normal sprite or as a fast sprite when it is parented to an CCSpriteSheet .

For the moment, CCSpriteSheet has the same limitations as AtlasSpriteManager . Limitations of CCSpriteSheet :

• Only accepts CCSprites as children
• CCSprites must have the same texture id as the CCSpriteSheet
• CCSprites can't contain children. Only 1 level of children is supported

Updating Animation

Migrating Animation to CCAnimation

v0.8 code:

Animation *
sapusAnim =
 [
Animation animationWithName:
@
"select"
 delay:
0.3f images:
@
"SapusSelected1.png"
, @
"SapusSelected2.png"
, @
"SapusSelected1.png"
, @
"SapusUnselected.png"
, nil
]
;

v0.99 code:

CCAnimation *
sapusAnim =
 [
CCAnimation animationWithName:
@
"select"
 delay:
0.3f]
;

[
sapusAnim addFrameWithFilename:
@
"SapusSelected1.png"
]
;

[
sapusAnim addFrameWithFilename:
@
"SapusSelected2.png"
]
;

[
sapusAnim addFrameWithFilename:
@
"SapusSelected1.png"
]
;

[
sapusAnim addFrameWithFilename:
@
"SapusUnselected.png"
]
;

Migrating AtlasAnimation to CCAnimation

v0.8 code:

AtlasAnimation *
animFly =
 [
AtlasAnimation animationWithName:
@
"fly"
 delay:
0.2f]
;

[
animFly addFrameWithRect:
 CGRectMake(
64
*
0
, 64
*
0
, 64
, 64
)
]
;

[
animFly addFrameWithRect:
 CGRectMake(
64
*
1
, 64
*
0
, 64
, 64
)
]
;

[
animFly addFrameWithRect:
 CGRectMake(
64
*
2
, 64
*
0
, 64
, 64
)
]
;

v0.99 code:

CCAnimation *
animFly =
 [
CCAnimation animationWithName:
@
"fly"
 delay:
0.2f]
;

[
animFly addFrameWithTexture:
spriteSheet.texture rect:
CGRectMake(
64
*
0
, 64
*
0
, 64
, 64
)
]
;

[
animFly addFrameWithTexture:
spriteSheet.texture rect:
CGRectMake(
64
*
1
, 64
*
0
, 64
, 64
)
]
;

[
animFly addFrameWithTexture:
spriteSheet.texture rect:
CGRectMake(
64
*
2
, 64
*
0
, 64
, 64
)
]
;

Taking advantage of CCSpriteFrameCache

One of the benefits of v0.99 is the CCSpriteFrameCache class, since it lets you write animation code more easily.

CCSpriteFrameCache is an sprite frame cache. Basically you can add frames to this cache, and you can get them by name. You can easily create an animation using the frame cache.

CCSpriteFrameCache supports the Zwoptex format. The zwoptex format is easy to parse and use. In case you decide not to use use, you can also add sprite frames to the cache by adding them manually, or by adding them with an NSDictionary .

eg:

// loads the sprite frames from a Zwoptex generated file


[
[
CCSpriteFrameCache sharedSpriteFrameCache]
 addSpriteFramesWithFile:
@
"animations/grossini.plist"
]
;

 

NSMutableArray

 *
animFrames =
 [
NSMutableArray

 array]
;

for
(
int
 i =
 0
; i < 14
; i++
)
 {
		

	CCSpriteFrame *
frame =
 [
[
CCSpriteFrameCache sharedSpriteFrameCache]
 spriteFrameByName:
[
NSString

 stringWithFormat:
@
"grossini_dance_%02d.png"
,(
i+
1
)
]
]
;

	[
animFrames addObject:
frame]
;

}


 

CCAnimation *
animation =
 [
CCAnimation animationWithName:
@
"dance"
 delay:
0.2f frames:
animFrames]
;

Tips

ADD YOUR OWN EXPERIENCE HERE

Recommendations based on the experience migrating games to v0.99:

• Automatically replace: [Director to [CCDirector
• Automatically replace: TextureMgr to CCTextureCache
• Automatically replace: sharedTextureMgr to sharedTextureCache
• Be careful when replacing sprites.

Here's my blog entry about performing the transition: http://paulhart.ca/?p=12

I had to Replace

• Sprite* s = [AtlasSprite spritWithRect:… spriteManager:mgr]

with

• CCSprite s = [mgr createSpriteWithRect:…]

I found this useful when loading images i.e. UIIMage into a CCAnimation

CCAnimation *
an =
 [
CCAnimation animationWithName:
@
"MyOverlayAnimation"
 delay:
0.5
]
;	// :dbolli:091129 11:08:00 Init animation with no textures	// :dbolli:091205 11:15:50 Removed param 3 textures:nil for cocos2d 9.x


 

UIImage *
myOverlayImage =
 [
UIImage imageNamed:
@
"my overlay.png"
]
;

// :dbolli:091205 11:18:57 Note: This image is an example placeholder for a UIImage created on the fly within the app. addFrameWithFilename: above is the easiest way to simply load an image...


 

[
an addFrameWithTexture:
[
[
CCTexture2D alloc]
 initWithImage:
myOverlayImage]
 rect:
CGRectMake(
 0.0
, 0.0
, CGImageGetWidth(
myOverlayImage.CGImage)
, CGImageGetHeight(
myOverlayImage.CGImage)
)
]
;	// :dbolli:091205 11:18:57 Added param 2 rect:CGRectMake for cocos2d 9.x

Regards, Derek Bolli (dbolli)