cocos2d for iPhone v0.8 RC2 Release Notes

You can download cocos2d for iPhone v0.8 RC2 from here:

http://cocos2d-iphone.googlecode.com/files/cocos2d-iphone-0.8-rc2.tar.gz

You can find the v0.8 documentation here:

• API Reference: API reference v0.8
• Programming Guide: Programming Guide v0.8

If you use actions, v0.8.0 can be 30% faster (or more) than v0.7.3 If you don't use actions, the performance should be more or less the same. To understand how fast cocos2d v0.8 is, please see the performance tests:

• v0.8 Performance Test

Issues #211, #307, #362, #402, #422

A singleton that dispatches touches like in v0.7.x (Standard) or one touch at the time (Targeted). The benefits of using Targeted touches is that you only receive the events (begin, move, end, cancel) of the touch that you claim. Using Targeted touches simplifies the touch handling code both in multi-touch and single-touch games. Unless you need a complex touch handling code, the use of Targeted touches is recommended.

Another benefit of the new TouchDispatcher is that it has a priority-queue, so you can alter the position of the touch consumers.

Example:

• cocos2d/Menu.m
• tests/TouchesTest

cocos2d uses it internally for the menu handling.

Issues #406

The Box2d physics engine was integrated within cocos2d. Box2d features: features

Example:

• tests/Box2dTest.mm

This feature is experimental.

Issues #407, #415, #431, #432, #433, #440

A new sound engine was integrated into cocos2d. One of the main features is its simplicity and the capacity to play 32 sounds simultaneously. Example:

• tests/CocosDenshionDemo

Important: CocosDenshion uses a license that although being compatible with the cocos2d for iPhone license is a bit more restrictive: CocosDenshion License

For further information, please read:

• CocosDenshion faq
• CocosDenshion cookbook

Issues #317 ,#344 ,#382 ,#425

A new way to create labels object from TTF fonts was added. The class is called BitmapFontAtlas.

You can create nice labels with gradients, shadows, and other effects. Also you can manipulate each letter individually, like if they were AtlasSprite objects. To create the fonts, you can use this font editor.

Example:

• tests/AtlasTest.m

Issue #125

By default all .PNG images in iPhone, have their alpha channel premultiplied. So the blending function and the opacity needs to be calculated differently when you treat an image with alpha premultiplied.

Since v0.8 the opacity and blend function will be applied according to the alpha premultiplied value of the image. You can modify the default behavior by calling:

[sprite setOpacityModifyRGB:NO];   // example of using glColor(r,g,b,opacity);
[sprite setBlendFunc: (ccBlendFunc) { GL_SRC_ALPHA, GL_ONE }];  // example of additive blending

Example:

• tests/Texture2dTest.m

Issues #437, #451

ActionManager is a singleton that handles all the actions. It knows how to run / pause / resume / stop the actions. The action's logic that was inside of every CocosNode was removed, but, to preserve compatibility the CocosNode API remains untouched.

The benefits of the ActionManager are:

• You can run actions against any kind of object. eg: against CocosNode objects(like in v0.7), against sound objects, against other actions, etc.
• Code is simpler to maintain: less bugs and more room to make performance improvements
• CocosNode objects are lighter

Example of an action running against another action:

-(void) onEnter
{
    [super onEnter];
 
    // create a Lens action
    id lens = [Lens3D actionWithPosition:ccp(20,120) radius:140 grid:ccg(32,24) duration:10];
 
    // create a jump / jump back action
    id jump = [JumpBy actionWithDuration:5 position:ccp(300,0) height:100 jumps:4];
    id jump_back = [move reverse];
    id seq = [Sequence actions: jump, jump_back, nil];
 
    // run the Jump action against the Lens action!!
    [[ActionManager sharedManager] addAction:seq target:lens paused:NO];
 
    // run the lens action (using the v0.7 API) against self
    [self runAction: lens];
}

Full example:

• tests/EffectAdvancedTest.m

A new template project was added. The purpose of this project is to start a cocos2d game from scratch. To open this project you can do:

$ cd cocos2d-iphone-0.8/tests/samples/MyFirstGame/
$ open MyFirstGame.xcodeproj

Issue #301

The code that executes actions was refactored. The target is not retained anymore, and the logic is a little bit different. The gain was a 20% percent boost when executing actions.

Issue #313

The bezier path BezierBy action was added. Example:

• tests/SpritesTest.m

Issue #172

Transitions now emit the onEnter and onExit signals to the ingoing and outgoing scenes just once ( in v0.7.x those signals were emitted twice causing some headaches to developers).

Also, a new signal was added: onEnterTransitionDidFinish.

This new signal is called when:

• If your scene enters the stage without a transition, then it is called right after onEnter
• If your scene enters the stage with a transition, then it is called when the transition finishes.

The idea is to initialize code that might be “heavy” (eg: load sounds/music) on onEnterTransitionDidFinish to prevent hangs on the transition.

Example:

• tests/TransitionTest.m

Issue #117

Now it is easier to remove only the unused textures from the TextureMgr by calling:

  [[TextureMgr sharedTextureMgr] removeUnusedTextures];

The unused textures are the ones that have a retain count of 1.

Example:

• tests/Texture2dTest.m

Issue #420

You can load any kind of texture asynchronously. The TextureMgr has a new method to load asynchronously (and cache) the textures. TextureMgr API:

/* Returns a Texture2D object given an file image
 * If the file image was not previously loaded, it will create a new Texture2D object and it will return it.
 * Otherwise it will load a texture in a new thread, and when the image is loaded,
 * the callback will be called with the Texture2D as a parameter.
 * The callback will be called from the main thread, so it is safe to create any cocos2d object from the callback.
 * Supported image extensions: .png, .bmp, .tiff, .jpeg, .pvr, .gif
 */
-(void) addImageAsync:(NSString*) filename target:(id)target selector:(SEL)selector;

Full example:

• tests/Texture2dTest.m

Issue #349

/*Returns a Texture2D object given an CGImageRef image
 If the image was not previously loaded, it will create a new Texture2D object and it will return it.
 Otherwise it will return a reference of a previously loaded image
 The "key" parameter will be used as the "key" for the cache.
*/
-(Texture2D*) addCGImage: (CGImageRef) image forKey: (NSString *)key;

Issues #347, #365, #366, #383, #412

The MenuItem code was simplified and now it's much easier to subclass it to support any kind of MenuItem.

The new supported MenuItem objects are:

• BitmapFontAtlas is supported by using the MenuItemLabel
• AtlasSprite: by using MenuItemAtlasSprite
• Sprite: by using MenuItemSprite. (Note: MenuItemSprite is different from MenuItemImage)

The new MenuItemLabel has a new property: disabledColor

Example of the new features:

• tests/MenuTest.m

Issue #303

A new property, called anchorPoint was added to CocosNode. It lets you modify the anchor point of a given node by using normalized coordinates. The default value is 0.5,0.5 (center of the node).

An anchorPoint of (1,1) is the top-right corner, while (0,0) means the bottom-left corner.

The old transformAnchor property is still being used internally, but you can't modify it anymore.

To upgrade your code from v0.7.3 to v0.8 you need to do the following:

v0.7.3 API

    // image size is(400,300)
    [node setTransformAnchor: ccp(200,200)];        // absolute pixels

v0.8 API

    // image size is(400,300)
    [node setAnchorPoint:ccp( 0.5f, 2/3.0f)];       // relative (1,1) is top-right
                                                    // (0,0) is bottom-left
                                                    // (0.5f, 0.5f) is the middle

Also the not so used property relativeTransformAnchor was renamed to relativeAnchorPoint.

Example:

• tests/cocosnodeTest.m

Also read compatibility_issues.

Issue #263

Thanks to the cache that was implemented in CocosNode, now all the local to world coordinates functions and vice-versa are much faster

Issue #355

It's possible to change the OpenGL Z vertex of any CocosNode by changing the vertexZ property:

[sprite setVertexZ:100];

Warning: Use this feature only if you understand how OpenGL and cocos2d work.

Example:

• tests/AtlasSpriteTest.m

Issues #XXX, #443

All CocosNode objects now has a size. To obtain this value or to modify it, you should do:

//read
CGSize size = [node contentSize];
 
// write
CGSize newSize = CGSizeMake(100,200);
[node setContentSize:newSize];

Issue #164

Now it's possible to enable/disable the touches or the accelerometer in runtime. Example:

@implementation MyLayer
-(void) condition
{
   // It's important to use the 'self.isXXX' and not the 'isXXX'
   if( somethingHappens )
      self.isTouchEnabled = NO;
   if( somethingElseHappends )
      self.isAccelerometerEnabled = YES;   
}

Issue #339

API changes:

Issues #241, #245, #335, #367, #385, #401

The particle engine was refactored, and now the ParticleSystem object has 2 subclasses: PointParticleSystem and QuadParticleSystem. Benefits of QuadParticleSystem:

• Support for particles bigger than 64 pixels
• Support for spinning particles
• The whole emitter can be scaled

As you can see QuardParticleSystem has more features than PointParticleSystem but it is also a little bit slower. See performance in v0.8-beta to compare the performance between PointParticleSystem and QuadParticleSystem.

New features added to the main Particlesystem:

• Support for Free and Grouped position
• Support for varying size particles
• Support for auto-remove-on-finish

Example:

• tests/ParticleTest.m

Both, PointParticleSystem and QuadParticleSystem, are using interleaved data array. In theory it should give them some performance boost over none interleaved data array, but in practice it is giving the same performance.

Issue #226

The API to manipulate the alias / antialias property of a texture was refactored. Now it is possible to change that property by calling instance methods, instead of calling class methods, making the API simpler.

v0.7.3 API:

	// Aliased images
	[Texture2D saveTexParameters];
	[Texture2D setAliasTexParameters];
 
	TileMapAtlas *tilemap = [TileMapAtlas tileMapAtlasWithTileFile:@"tiles.png" mapFile:@"levelmap.tga" tileWidth:16 tileHeight:16];
 
	[Texture2D restoreTexParameters];

v0.8 API:

	TileMapAtlas *tilemap = [TileMapAtlas tileMapAtlasWithTileFile:@"tiles.png" mapFile:@"levelmap.tga" tileWidth:16 tileHeight:16];
 
	// Aliased images
        [tilemap.textureAtlas.texture setAliasTexParameters];

Example:

• tests/Texture2dTest.m

Issue #359

The TextureAtlas class was refactored. It now uses interleaved data array, instead of non-interleaved data array. In theory it should perform better, but in practice it is performing as in v0.7.x.

Also, in v0.7.x the color parameter was optional. In v0.8 the color is always used, occupying a little bit more of memory.

Example:

• tests/AtlasTest.m

Issue #358

The parallax scroll logic was removed from CocosNode and was added in a new class called ParallaxNode. The CocosNode#transform logic is now simpler and easier to maintain.

Parallax v0.7.3 API:

    id node = [CocosNode node];
    id child1 = [Sprite ...];
    [node addChild:child1 z:0 parallaxRatio:ccp(ratioX, ratioY)];

Parallax v0.8 API:

    id parallax = [ParallaxNode node];          // <-- ParallaxNode is the only one that suports parallax ratio 
    id child1 = [Sprite ...];
    [parallax addChild:child1 z:0 parallaxRatio:ccp(ratioX, ratioY) positionOffset:ccp(offsetX,offsetY)];

Example:

• tests/ParallaxTest.m

Issue #351

It is now possible to use all 4 possible orientations:

• Landscape left (like in v0.7.x)
• Portrait (like in v0.7.x)
• Landscape right (new)
• Portrait upside-down (new)

The old API is still present, but it is tagged as deprecated. In v0.9 it will be removed. New API example

    ccDeviceOrientation = [[Director sharedDirector] deviceOrientation];
    [[Director sharedDirector] setDeviceOrientation: CCDeviceOrientationLandscapeLeft];
    [[Director sharedDirector] setDeviceOrientation: CCDeviceOrientationPortrait];

Full Example:

• tests/drawPrimitives.m

Director doesn't handle the touches anymore, so you need to update your code.

Old API:

    [[Director sharedDirector] setEventsEnabled: state];

New API:

    [[TouchDispatcher sharedDispatcher] setDispatchEvents: state];

Issue #236

It is possible to create a slow motion or fast forward effect to the whole scene. It affects every scheduled method, including running actions.

// value
//  1: means standard speed
//  <1: slow motion values
//  >1: fast forward value
[[Scheduler sharedScheduler] setTimeScale: value];

Example:

• tests/EaseActionsTest.m

Issue #429, #452

The 1st time a Timer or an Action is fired, it will be with a dt=0. Transitions and other timer-based classes will start from 0, making them look smoother.

Issue #380

The drawing primitives can now draw bezier curves. Example:

• tests/drawPrimitives.m

Compatibility issues with version 0.7.2 and v0.7.3

All the deprecated functions from v0.7.2 / v0.7.3 were removed.

So, all the changes that were “optional” in v0.7.2 / v0.7.3 are required in v0.8.0

For more information read the following files:

• convert_0_7_0_to_0_7_1.txt
• convert_0_7_1_to_0_7_2.txt

Old:

position = ccp(0,0);
rotation = 90;
scale = 2;

New:

self.position = ccp(0,0);  // use them as properties
self.rotation = 90;
self.scale = 2;

The following files were added to cocos2d:

• ActionManager.h
• ActionManager.m
• BitmapFontAtlas.h
• BitmapFontAtlas.m
• DrawingPrimitives.h
• DrawingPrimitives.m
• ParticleExamples.h
• ParticleExamples.m
• ParticleSystem.h
• ParticleSystem.m
• PointParticleSystem.h
• PointParticleSystem.m
• QuadParticleSystem.h
• QuadParticleSystem.m
• ParallaxNode.h
• ParallaxNode.m
• TouchDispatcher.h
• TouchDispatcher.m
• TouchHandler.h
• TouchHandler.m
• TouchDelegateProtocol.h
• Support/ccHashSet.h
• Support/ccHashSet.m

The following files were removed from cocos2d:

• CocosNodeExtras.h
• CocosNodeExtras.m
• Particle.h
• Particle.m
• ParticleSystems.h
• ParticleSystems.m
• Primitives.h
• Primitives.m
• Support/UIColor-OpenGL.h
• Support/UIColor-OpenGL.m

Old:

[sprite setRGB:255:128:64];
GLubyte r = [sprite r];
GLubyte g = [sprite g];
GLubyte b = [sprite b];

New:

[sprite setColor:ccc3(255,128,64)];
ccColor3B color = [sprite color];

• Actions: Repeat repeats OK (issue #424)
• Actions: Prevents division by 0 when duration==0 (issue #452)
• ActionManager: 5% increase in performance (issue #451)
• CocosDenshion: fixed clicking on looped waves sounds (issue #440)
• CocosDenshion: Added properties in SimpleSondEngine (issue #454)
• CocosLive: using the deprecated CString API (issue #441)
• CocosLive: send-score object can be reused (issue #417)
• CocosNode: children is an explicit “property” (issue #411)
• CocosNode: relativeTransformAnchor → relativeAnchorPoint (part of issue #303)
• ColorLayer: uses floats instead of ints for its size (issue #339)
• ColorLayer: updates contentSize when when size is used (issue #443)
• Demos: added basic template to start new projects (issue #447)
• Director: FastDirector with fast events or not at compile time (issue #449)
• FileUtils: Absolute paths are not converted (issue #352)
• Menu: MenuItems works with anchorPoint correctly (issue #412)
• Menu: ItemLabel disabled color is configurable. color is saved (issue #366)
• Particle: VBO update only the needed particles (issue #367)
• TextureMgr: new (and recommended) way to add CGImages (issue #349)
• TouchDispatcher: retains/releases the delegates (issue #422)
• Transitions: Fixed artifacts in Slide transitions (issue #442)

For further information, please read the full changelog: CHANGELOG