Learn & Master Cocos2D Game Development

This is a collection of Tips & Tricks for users who are migrating to cocos2d-iphone v3 from v2. Mostly refers to questions posted on stackoverflow.com.

Please excuse the short, bullet-pointed format. I’m a little short on time but didn’t want to miss out on another biweekly post like I did two weeks ago (first time in about 4 years, ouch).

General Tips

• Many classes have been renamed…

“Use the source, Luke!” If you don’t find what you are looking for:
- Check the cocos2d API class reference
- Start typing the class or method name, see what suggestions Xcode autocomplete has for you
- Use part of the class name (ie “repeatforever”) and perform a “Find in Project” to search through all source code files

• Tutorial XYZ won’t work with v3!

Yes, it won’t. Most likely it was written for cocos2d-iphone v2.
Question is: do you have to use v3? And do you have to use it right now?
Because if you’re in the process of learning cocos2d it’ll be easier to learn from and with v2 tutorials/books for the time being until more v3 tutorials have been published.

• How to upgrade an existing cocos2d v2 project to v3?

Not trivial. Similar if not the same process as before but expect a host of problems due to massive changes to the cocos2d API. The larger the project the less feasible porting to v3 is.

Tip: Finish the project with v2 and start your next project with v3. Consider that v3.0 brings significant changes and v3.1 will feature a radically overhauled renderer, so you may want to (what I’m really saying: should) wait out these changes if you’re in the middle of a development cycle.

• Send messages directly instead of CCCallFunc

I noticed some users use runAction with CCCallFunc where they could simply send a message to the object. Also seen this done by Sprite Kit users.
This explains what I mean.

• Don’t forget to call [super ..] in your AppDelegate methods

Case in point: applicationDidBecomeActive did not resume cocos2d without calling its super implementation.

Specific Tips

• How to find a Node by tag?

Tags have been replaced by CCNode name property.
There are corresponding removeChildByName: etc methods available.

• Where is CCSomeAction?

Most CCAction classes have been renamed. All follow consistent naming scheme by starting with “CCAction..”
Example: CCRepeatForever is now named CCActionRepeatForever

• Argh! CCCallBlockN, CCCallBlockND are gone. And so are CCActionCallFuncN and CCActionCallFuncND.

They were never really needed. And CCActionCallFuncN and ND were in fact dangerous to use with ARC.
Use CCCallBlock as described here, replaces all of the 4 above without any loss in functionality due to the way blocks work (they have access to variables in scope).
Alternatively schedule an update selector.

• How to use Sprite frame animations?

The API has changed. There are plenty of examples: here, here, here and here.

• CCNodeColor is always opaque

The opacity property has been changed from byte (0-255 value range) to CGFloat (0.0 to 1.0 value range). That means values greater than 1 will make the color node opaque. Divide your value by 255, for example 128 / 255 = 0.5

• How to enable touch input and accelerometer?

self.accelerometerEnabled, self.touchEnabled have been removed. Use self.userInteractionEnabled instead. Or migrate to Sprite Kit, that works too. 😉
Also note CCResponder is now the base class of all nodes which provides a similar functionality to UIResponder/NSResponder in terms of user input.
Here’s a cocos2d v3 touch handling tutorial.

• How to enable Multi-Touch?

See here.

• Where are CCMenu, CCMenuItem, etc?

Gone. Replaced by CCButton and others. Look into cocos2d-ui folder for more UI classes. Here’s an example for CCButton with different color when pressed.

• How to play sounds/music in v3?

CocosDenshion / SimpleAudioEngine have (thankfully) been replaced by ObjectAL / OALSimpleAudio, examples here and here.
More about ObjectAL and ObjectAL documentation / reference.

• Where is my favorite scene transition?

Yes, some transitions are missing from CCTransition in v3 RCx.

• What is cocos2d’s UIViewController?

CCDirector is! Some examples here and here and here’s how to present another view controller on top of cocos2d:

• How to get director’s winSize?

CCDirector winSize property is now named viewSize.

• Where’s the AppController?

It’s been renamed back to AppDelegate.

• How to integrate iAd in cocos2d-iphone v3?

Here’s an example and here’s how to hide an iAd banner view.

• How to use a custom shader program with CCSprite?

Here is one example and another one.
Warning: there’s a reason why this API is now private, use with caution. Also v3.1 will have a different renderer, so this method of accessing the shader property is likely to change with v3.1.

• How to set Portrait orientation

Read this.

• What’s a Chipmunk replacement for Box2d’s mouse joint?

Here’s a good workaround.

• How to make a UIScrollView pass-through touches to a CCButton?

You may find this helpful.

Missing or unclear

• How to put a camera view in the background

Should be the same procedure as in v2 but users are having issues applying v2 code to v3.
Maybe it doesn’t work anymore, or maybe it just needs someone to figure out how to make it work.

• Where are the Javascript bindings?

They have been removed and won’t come back.
PS: For JS development with cocos2d you could use cocos2d-x / cocos2d-html5 but there are a number of very good JS cross-platform development solutions out there so unless you’re fixated on cocos2d you should research other JS game engines and decide which one best fits your purpose.

• Where’s the Box2D template (integration)?

None. Box2D template/integration may or may not be coming in the future.
It’s definitely not a high priority because cocos2d physics focus is on Chipmunk integration. Adding another physics engine would double the work done in both cocos2d and SpriteBuilder, so I find it very unlikely that cocos2d will integrate Box2D as much as it does Chipmunk currently. You can however always add the Box2D files to your project and start using it, but synchronizing sprite position/rotation with physics bodies and memory management of bodies will be up to you.