Monday, August 19, 2013

Cocos2D & CocosBuilder Version Decoder

Just now I got a great question from a viewer on my YouTube channel about Cocos2D & CocosBuilder versioning.  I'm going to post my answer here as it might help a few folks.

CocosBuilder icon - see below for CocosBuilder project URL
CocosBuilder for the Win!

Versions

Versions in Cocos2D can be really confusing - and its no fault of the Cocos2D guys as the stack is a collection of Open Source projects and as such the different components do not have nicely matching version numbers.

For example, right now, you need version 3.0alpha of CocosBuilder to work with version 2.1 of Cocos2D.  You read that right - v3.0 of CCB goes with v2.1 of Cocos2D.  They are different projects and although the guys are working hard to make coordinated releases now, its still confusing.

If you're using the stack I do, which is CocosBuilder and Cocos2D-iPhone then it's easy to get hold of the wrong software packages and get weird errors, with undeclared variables.  Another issue you can find is that at run-time you get an error saying that the CCB data files are from an incompatible version of CocosBuilder.

See my previous post on upgrading versions for a video about this issue and some tips about navigating the versions of Cocos2D.  Executive summary: use the Cocos2D-iphone blog posts to find the latest "coordinated release".

As I write this, for example, the versions you probably want are:
These should work together just fine.  Obviously you'll want to use the latest "known good" combination (which might be later than the above depending on when you read this post!).

Release Quality

Another issue with versioning is that while Cocos2D v2.1 has been in "release candidate" for a little while, and we've seen version quality tags like v2.1rc1 or similar as a result: now v2.1 is out and we are back to a major dot-point release.  So nice work by Ric and Birkemose and the guys for getting that up to release quality.

But: we are still in alpha on CocosBuilder - if you're like me you want to work with more stable software.  However here we have to bite the bullet and work with 3.0alpha, at the time of writing, because that is the matching CCBReader for Cocos v2.1.  It is what it is and I guess Viktor Lidholt and other volunteers are working hard on CocosBuilder with what time they have spare to get it out of alpha.  I have not found any real issues so I suggest ploughing ahead with the 3.0alpha builds at this time.

Using the CocosBuilder Source

Note that the link to CocosBuilder above is to the "full source code", not to the "application".  Once you unzip the CocosBuilder full source code, drill down into the CocosBuilder directory with Finder to locate the CocosBuilder.xcodeproj file and double-click that to open it in XCode.  

Once open in XCode you can get your shiny new CocosBuilder binary by selecting the target "CocosBuilder" > "My Mac 64bit" from the Schemes drop-down (top-left in XCode, next to the run & stop buttons) and pressing "Run".  Once CocosBuilder is running, right-click on it's icon in the Dock and choose "Keep in Dock" so you can find it again easily.  

If you lose track of it, its stored under the "build" sub-directory of wherever you unzipped your sources.

Why go through all this if you can just download the binary?

I do it this way so I can be sure I have the matching sources.  If you're just building HTML/Javascript apps, and don't care about iPhone you don't need the sources and can just use the pre-built binary.  But to work with ObjC on the iPhone you need the sources.

Could you download the pre-built binary AND the sources?  Sure.  I don't have masses of room on the SSD on my laptop so I try to save a bit my just building out of the sources but you can use the pre-built binary if you like - just make sure you get the matching one for the sources!

I also like that under the CocosBuilder unzipped source tree you'll find a full documentation set; the Cocos Player application is there and also the full sources to the Example applications.

To get the correct CCBReader that will match your CocosBuilder, use the one from the Examples.  In the case of the above the folder you want is at this path:

$unzipped_source_tree/Examples/CocosBuilderExample/libs/CCBReader

Possible CocosBuilder v3.0alpha5 Issues

One final note, is that there seem to be a couple of new experimental features like the image previewer pane, on CocosBuilder v3.0alpha5, which seemed a bit clunky - hence I am actually currently using v3.0alpha4 which I find works just great for me.

I haven't reported those issues because I have just been too busy to spend time isolating them, but if you try v3.0alpha5 and see a problem take a screenshot and report it on the CocosBuilder GitHub.  You can probably revert back to 3.0alpha4 until the problem is fixed.