cocos2d for iPhone v0.99.0-rc Release Notes

You can download cocos2d for iPhone v0.99.0-rc from here:

http://cocos2d-iphone.googlecode.com/files/cocos2d-iphone-0.99.0-rc.tar.gz

_{cocos2d v0.99.0-rc is SVN revision 1759}

You can find the v0.99.0-rc documentation here:

• API Reference: API reference v0.99.0-rc
• Programming Guide: Programming Guide

To understand how fast cocos2d v0.99.0-rc is, please see the performance tests

• v0.99.0-rc Performance Test

Issue #712

cocos2d v0.99 is screen resolution independent. It means that it works with an screen resolution of 480×320 / 1024×768 or with any other screen resolution. It means it works with iPad.

• To test cocos2d with iPad, you need to download iPhone SDK 3.2 http://www.apple.com/ipad/sdk/
• To make your projects work at 1024×768, you need to convert them into iPad projects. Please, read the SDK documentation to learn how to do it.

Also it is possible to load textures of 2048×2048 in devices where it is supported (iPhone 3GS and probably the iPad).

Issue #520

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

For further info, please see: Migrating to v0.99

Issue #620

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...];
[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.

But CCSpriteSheet has some limitations:

• Only accepts CCSprites as children
• CCSprites must have the same texture id as the CCSpriteSheet

The animation code in v0.99 was also merged:

• Animation → CCAnimation
• AtlasAnimation → 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"];

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)];

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];

For further info, please see: Migrating to v0.99

Issues #346, #665

// Create an SpriteSheet
CCSpriteSheet *sheet = [CCSpriteSheet spriteSheetWithFile:@"animations/grossini.png" capacity:50];
 
// Add sprite sheet to parent
[self addChild:sheet];
 
// Load sprite frames	
[[CCSpriteFrameCache sharedSpriteFrameCache] addSpriteFramesWithFile:@"animations/grossini.plist"];
 
 
CCSprite *sprite1 = [CCSprite spriteWithSpriteFrameName:@"grossini_dance_01.png"];
[sprite1 setPosition:ccp( s.width/3, s.height/2)];
 
CCSprite *sprite2 = [CCSprite spriteWithFrameFrameName:@"grossini_dance_02.png"];
[sprite2 setPosition:ccp(50,50)];
 
CCSprite *sprite3 = [CCSprite spriteWithSpriteFrameName:@"grossini_dance_03.png"];
[sprite3 setPosition:ccp(-50,-50)];
 
[sheet addChild:sprite1];
 
// NEW NEW NEW
// sprite1 supports children
[sprite1 addChild:sprite2];
[sprite1 addChild:sprite3];

Full example:

• SpriteTest.m

Issue #643

Suppose that you want to create a health bar on top of your sprite. The easiest way to do it is by adding the health bar as a child of your sprite. This works as expected expect if you sprite rotates, since the health bar will rotate too. To prevent this behavior the CCSprite object has a new property: honorParentTransform.

By default the child (in our example, the “health bar”) will rotate, translate and scale relative to it's parent. But we can override this behavior by:

// default value
healthBar.honorParentTransform = CC_HONOR_PARENT_TRANSFORM_ALL;
 
// ignores parent rotation
healthBar.honorParentTransform &= ~CC_HONOR_PARENT_TRANSFORM_ROTATE;
 
// ignores parent scale
healthBar.honorParentTransform &= ~CC_HONOR_PARENT_TRANSFORM_SCALE;
 
// ignores parent scale
healthBar.honorParentTransform &= ~CC_HONOR_PARENT_TRANSFORM_TRANSLATE;

Full example:

• SpriteTest.m

Issue #627

The CCAnimate action now supports reverse. Example:

id action = [CCAnimate actionWithAnimation: animation restoreOriginalFrame:NO];
id action_back = [action reverse];
 
[sprite runAction: [CCSequence actions: action, action_back, nil]];

Since part of issue #620 was rollbacked, these 2 Instant Actions where added.

Example:

CCSequence *seq = [CCSequence actions: animate,
				   [CCFlipX actionWithFlipX:YES],
				   [[animate copy] autorelease],
				   [CCFlipX actionWithFlipX:NO],
				   nil];
 
[sprite runAction:[CCRepeatForever actionWithAction: seq ]];

Issue #390

CCRepeat and CCRepeatForever repeat the action without jerking. The repetitions are smooth now.

Issue #705

• CCRotateTo works as expected when it is part of a CCRepeat action.

Issue #XXX

• CCSequence performance was improved between 30~50%. Instead of using an NSArray is uses a C array.

Issues #610, #612, #730,

• CCBitmapFontAtlas works with subdirectories.
• setString doesn't override color
• Improved creation and update time in about 100%

Example:

// subdirectory
CCBitmapFontAtlas *label1 = [CCBitmapFontAtlas bitmapFontAtlasWithString:@"Test" fntFile:@"fonts/bitmapFontTest2.fnt"];
[self addChild:label1];
 
// color
[label1 setColor:ccRED];
[label1 setString:@"This is a red string"];

Issues #494, #739

• Box2d template doesn't generate warnings… or at least it doesn't generate billions of warnings.
• Box2d was updated to r39. You should specify body type.

Example:

b2BodyDef bd;
bd.type = b2DynamicBody; // default type is static body

Issue #378, #438

The camera object that belongs to CCNode was rewritten. And it is not 100% compatible with the old camera.

New features:

• Camera honors previos transformations.
• Cameras can be chained. A parent can have a camera, and its children too
• The center of the camera can be modified
• It is a little bit faster
• Works OK in any orientation

Limitations:

• It is not possible to zoom in the camera more than 100%.

For further information, please read: Discussion about the new camera implementation and its workaround

Issue #664

• Chipmunk was updated to v5.1.
• The Chipmunk test best was updated to use cocos2d
• The ChipmunkAccelTouch demo was updated to support chipmunk v5.1

Issue #597

• CCColorLayer supports the CCBlendProtocol. You can create “negative” images with it.

Full example:

• LayerTest.m

Issues #593 ,#595

• Added support for detecting ringer/mute switch state
• Doesn't crash when file has no extension

Issues #718

To improve the CCNode / CCSprite performance these changes were made:

• Node transformations (rotate,scale,position) are not performance with the glTranslate, glScale and glRotate calls. Instead a glMulMatrix is executed.
• The default GL state is:

	glEnableClientState(GL_VERTEX_ARRAY);	
	glEnableClientState(GL_COLOR_ARRAY);	
	glEnableClientState(GL_TEXTURE_COORD_ARRAY);
	glEnable(GL_TEXTURE_2D);

So, for example if your node only needs GL_TEXTURE_2D, you should do:

-(void) draw
{
// Default GL states: GL_TEXTURE_2D, GL_VERTEX_ARRAY, GL_COLOR_ARRAY, GL_TEXTURE_COORD_ARRAY
// Needed states: GL_TEXTURE_2D, 
// Unneeded states: GL_VERTEX_ARRAY, GL_COLOR_ARRAY, GL_TEXTURE_COORD_ARRAY
 
	glDisableClientState(GL_COLOR_ARRAY);
	glDisableClientState(GL_TEXTURE_COORD_ARRAY);
	glDisableClientState(GL_VERTEX_ARRAY);
 
[...] draw your stuff.
 
// restore GL default states
	glEnableClientState(GL_VERTEX_ARRAY);	
	glEnableClientState(GL_COLOR_ARRAY);	
	glEnableClientState(GL_TEXTURE_COORD_ARRAY);
}

For further information, please read this thread: http://www.cocos2d-iphone.org/forum/topic/3976

Issues #657

The only class that knows how to create sprites is CCSprite. The creation methods from CCSpriteSheet and CCSpriteFrameCache were removed. The benefits of this change, is that it is easier to create a subclass of CCSprite.

if you want to create an CCSprite subclass, you don't need to implement each of the initWithXXX method. You are safe by just implementing init:

Example:

@implementation MySprite
-(id) init
{
   if( (self=[super init]) )
   {
        ivar1 = xxx;
        ivar2 = yyy;
        ivar3 = zzz;
   }
   return self;
}
@end
 
// And to create an instance of MySprite you simply do:
MySprite *sprite = [MySprite spriteWithFile...];
 
// or
MySprite *sprite = [MySprite spriteWithSpriteSheet:....];
 
// or any of the supported CCSprite methods.

Issues #632, #697

• It's possible to generate mipmap textures in runtime.
• Simulator and Device display the same image, no matter if the have alpha premultiplied or not.

// mipmaps
CCTexture2D *texture0 = [[CCTextureCache sharedTextureCache] addImage:@"grossini_dance_atlas.png"];
// generate mipmap textures
[texture0 generateMipmap];
 
// update the tex parameters so MIPMAP_LINEAR is used
ccTexParams texParams = { GL_LINEAR_MIPMAP_LINEAR, GL_LINEAR, GL_CLAMP_TO_EDGE, GL_CLAMP_TO_EDGE };     
[texture0 setTexParameters:&texParams];

Full example:

• Texture2dTest.m

Issue #581

The CCTextureAtlas object (used by CCSpriteSheet) uses by default VBO instead of vertex array list.

Issue #539, #636, #689

• CCTMXTiledMap works with subdirectories.
• Added support for object_group
• Works as fast as in v0.8.2
• Fixed memory corruption when removing children

Example:

// subdirectory example
CCTMXTiledMap *map = [CCTMXTiledMap tiledMapWithTMXFile:@"TileMaps/orthogonal-test4.tmx"];
[self addChild:map z:0 tag:kTagTileMap];

Issue #710

The TouchDispatcher suffered a smal refactor. New features:

• It is a little bit faster than v0.8.x
• The standard handlers returns void and not BOOL
• The standar handlers are processed after the target handlers.

// v0.8 code
- (BOOL)ccTouchesEnded:(NSSet *)touches withEvent:(UIEvent *)event
{
    // do something
    return kEventHandled;
}
 
// v0.99 code
- (void)ccTouchesEnded:(NSSet *)touches withEvent:(UIEvent *)event
{
     // do something
}

For further information about the implementation of this feature, please read: http://www.cocos2d-iphone.org/forum/topic/3853#post-23061

Issue #646

• Added CCCrossFadeTransition. It fades in the incoming scene while the outgoing scene fades out.

Full example:

• TransitionsTest.m

Please see the Migrating to v0.99 wiki page.

All deprecated classes/methods in v0.8.x were removed from v0.99

Issue #620

MenuItemAtlasSprite was removed because:

• In v0.99 CCSprites supports rects
• MenuItemAtlasSprite was a hack. You needed to add the items in 2 different places and it wasn't obvious at all
• Usually you don't need a lot of performance to display a menu. If you have 20 items, the performance between MenuItemAtlasSprite and MenuItemSprite should be more or less equal

Since CCTextureNode was superseded by CCSprite, CCTextureNode was removed.

Steps to use the v0.99 cocos2d files:

• Open your game XCode project
• From XCode remove the (v0.8) 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

Full changelog: CHANGELOG

version 0.99.0-rc - 31-Jan-2010

• All: Default OpenGL state is: GL_TEXTURE_2D, GL_VERTEX_ARRAY, GL_COLOR_ARRAY, GL_TEXTURE_COORD_ARRAY (fixed issue #718)
• Action: Improved CCSequence performance (issue #XXX)
• BitmapFontAtlas: huge performance boost in update/create time (issue #730)
• Box2d: updated to r39 (issue #494)
• Camera: Offset fixed in landscape mode (issue #378)
• Camera: It's possible to orbit around any point (issue #438)
• Camera: Doesn't reset affine matrix (issue #XXX)
• Chipmunk: Using Chipmunk v5.1.0 (issue #664)
• Configuration: added object that knows GL capabilities and other misc stuff (issue #712)
• Director/Particles/Grid: removed hardcoded display size values. Using variable (issue #XXX)
• Director: send “cleanup” message to root scene when it is being replaced (issue #709)
• Effects: works independently of the display resolution (issue #XXX)
• Grid: optimized code. Only call camera.locate if it is dirty (issue #XXX)
• Node: Uses cached Affine matrix to transform the nodes (2 GL calls vs. 5 GL calls) (issue #XXX)
• Node: uses bits instead of bools when compiled with SDK >= 3_0 (issue #726)
• Node: uses “_” suffix for ivars (children_, isRunning_, tag_, etc..) (issue #733)
• Scheduler: removed support of repeats. Postponed for v0.99.1 (rolling back issue #630)
• Singletons: removed @syncronized() since cocos2d is not thread safe (issue #663)
• SpriteSheet: reorder updates descendants. Added test for this case (issue #708)
• Sprite: can create sprite from SpriteSheet. deprecated creation method from SpriteSheet (issue #657)
• Sprite: optimized rendering when using spriteSheet and subchildren (issue #XXX)
• Sprite: flip only flips the texture (not the anchor point and children) (issue #725)
• Templates: Updated to support v0.99, Chipmunk v5.1 and Box2D r39
• Templates: install_template.sh supports custom directory (issue #736)
• Templates: box2d+cocos2d template doesn't generate warnings… well only 2 warnings (issue #739)
• Tests: Works independently of the display resolution
• TextureNode: Removed Node. Superseded by Sprite
• TMXMaps: objectGroup support offsets (issue #689)
• TMXMaps: objectGroup: Simplified object creation. All objects are NSDictionaries. For custom objects, subclass TMXTiledMap (issue #636)
• TMXMaps: groupNamed renamed to objectGroupNamed (issue #XXX)
• TouchDispatcher: StandardTouchHandler returns void (not BOOL). They are executed after the TargetedHandlers (issue #710)
• XCode: doxygen scripts runs with spaces in subdirectories (issue #684)

version 0.9.0-beta - 11-Jan-2010

• Actions: added 2 new instant actions: FlipX and FlipY (counter-rollback of part issue #620)
• Actions: uses FLT_EPSILON constant (issue #701)
• Actions: prevent jerk in Repeat and RepeatForEver (issue #390)
• Actions: RotateTo can be repeated without losing information (issue #705)
• BitmapFontAtlas: doesn't override color when using setString (issue #610)
• Chipmunk: removed compiler warning on chipmunk demo (issue #680)
• CocosLive: added sanity checks on demo (issue #681)
• Director: removed compile warning on DisplayLink director (issue #682)
• Particles: prevent possible memory corruption when autoRemove is ON (issue #703)
• Scheduler: Supports repeat-number-of-times in scheduled selectors (issue #630)
• Sprite: anchor + offset + scale works (issue #671)
• Sprite: can create subclasses with an SpriteFrameName (issue #XXX)
• Sprite: flip works as scale * -1 (issue #690)
• Sprite: easier to subclass. [self init] is called (issue #485)
• Sprite: isFrameDisplayed works OK with offsets (issue #707)
• SpriteFrame: removed support for flipX and flipY (rollback of a part issue #620)
• SpriteFrameCache: If originalSize is not present, display warning (issue #670)
• SpriteSheet: adding grand-children doesn't crash (issue #676)
• SpriteSheet: child and children works OK with negative scales (issue #677)
• SpriteSheet: It is easier to subclass (issue #397)
• Templates: uses rfc1034identifier (issue #685)
• Texture2D: simulator treats pre-multiplied alpha images correctly (issue #697)
• TextureCache: doesn't crash when file not found. log error insted (issue #695)
• TMXTiledMap: added support for object and objectgroup (issue #636)
• TMXTiledMap: TMXLayer and TMXObjectGroup on it's own files (part of issue #636)
• TMXTiledMap: doesn't generate descendants when not necessary (works as fast as in v0.8.2)
• TMXTiledMap: removeChild works without corrupting the tilemap (issue #XXX)

version 0.9.0-beta - 14-Dic-2009

• ActionManager: fixed leak (issue #635)
• Actions: using [self class]. Easier to subclass (issue #655)
• Box2d: updated to r31 (pre 2.1.0) (issue #494)
• Chipmunk: updated to v5.0 (issue #664)
• CocosDenshion: support for detecting ringer/mute switch state (issue #593)
• CocosDenshion: doesn't crash when file has no extension (issue #595)
• ColorLayer: supports Blend Protocol (issue #597)
• Node: vertexZ is translated just once (issue #641)
• Director: call schedulers before glClear in mainLoop (part of issue #533)
• Director: “global” NSBundle to facilitate the integration of more than 1 game (issue #654)
• Particles: code easier to mantain, same performance
• Particles: small performance improvement (issue #661)
• SpriteSheet: supports any level of sub-children (issue #346, issue #665)
• Sprite: supports “honor parent transform” (issue #643)
• Sprite: displayFrame renamed to displayedFrame (issue #XXX)
• Sprite: fixed zwoptex offset & anchorPoint (issue #653)
• Sprite: setDisplayFrame works OK with different texture sizes (issue #666)
• Templates: using SDK 3.0 as base SDK
• Textures: supports mipmap generation (issue #632)
• Texture Atlas: uses VBO instead of vertex array list (issue #581)
• TextureCache: don't use autorelease pool to load images (issue #XXX)
• Tiles: TMX maps supports sub-directories (issue #539)
• Transition: added CrossFadeTransition (issue #646)

version 0.9.0-alpha - 18-Nov-2009

• All: using CC namespace (issue #520)
• All: prevents warnings with Static Analizer (issue #613)
• All: cocos protocols renamed to avoid confusion (part of issue #520)
• All: Added compatibility with v0.8 (part of issue #520)
• Animation: supports duration and reverse (issue #627)
• Tests: Performance Tests re-integrated to main XCode project (issue #XXX)
• BitmapFontAtlas: works with subdirectories (issue #612)
• Box2d: updated to r26 (pre 2.1.0) (issue #494)
• CocosLive: Uses CL namespace (part of issue #520)
• CocosLive: Uses ASCII encoder (issue #617)
• Sprite: Sprite and AtlasSprite merged in just one class (issue #620)
• Sprite: AtlasSpriteManager renamed to SpriteSheet (issue #620)
• Sprite: Sprite Frames and animations supports flipx / flipy (issue #620)
• SpriteFrameCache: added an easier way to create animations and sprites (issue #620)
• Templates: updated (part of issue #520 and issue #620)
• Templates: includes cocos2d and CocosDenshion licences files
• TextureMgr: renamed to TextureCache (part of issue #620)
• XCode: textures files in 1 xcode group (Texture2d, PVRTexture, TextureAltas, TextureCache)