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 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:

• Cocos2D v2.1
• CocosBuilder v3.0alpha5

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.

Room to Room

This new progress update video shows a bit of a milestone with our animated door sliding open and our heroine able to move to a new room.

I did all the room background artwork for the apartment a few weeks ago and I have been coding like a demon since then ironing out all the issues with moving from room to room and persisting the game state across view and room changes.

For those of you who are coders you might be interested in this aspect of CocosBuilder and Cocos itself - since it is scene based, and your scene is effectively your entire user-interface, moving to a new room basically tears down the whole UI, and it has to be rebuilt again from the CCB file for the next room or view.

This makes for some fun and games when an item has been modified in one view and you need it to reflect those modifications in a new view on the "same item".  Like wise with items that have been added to the inventory, and which to not appear in the next view.

Lastly of course the actual opening of doors and the logic with the character having to wait for the door to slide open before walking through had to be done.

This is done with action queueing which also took quite a while to get working properly.  So for example the sequence to go through to the walk-in-wardrobe is

• player taps the door to the wardrobe and says "Go"
• queue a GoTo  action to the wardrobe room
• that requires the door to be opened first so...
• queue a GoTo the door
• queue a Open of the door
• when the door open occurs it plays an animation of it sliding open
• finally execute the action to go to the wardrobe

This is all now working.  Whew!

CocosBuilder and CGPaths for non-rect Tap Detection

This is just a short post to frame a video how-to on detecting taps for selection on touchscreen devices, using CGPaths - and how to create those CGPaths using CocosBuilder.

What this essentially does is makes CocosBuilder into a tool that you can use to create non-rectangular bounding paths for tap detection.  As a bonus, I show how you can use the CGPath information to create a blue selection sprite image to signify the active selection in the UI.


I reference Bob Ueland's excellent CGPath tutorial, and that does include some code that you can use for the actual hit test.

For the extraction of the CGPath data from the CocosBuilder file I am not posting my code for cutting-and-pasting but if you've followed my earlier tutorials and are building your own game in Cocos2D you should have enough knowledge to follow what I have done.  It is just simply a case of traversing the nodes and using the standard method to build up a path from the CGPoint information stored in the CCNodes.

My technique for creating a selection sprite from the CGPath data is also not tricky - just check the documentation.  Give it a try and if you get really stuck feel free to ask a question here or on G+.

Hope it helps, and enjoy selecting stuff!

CocosBuilder Revolution

A couple of months ago now I threw away all my code and started again.

Was that a bad thing?  Well, it was bad in the sense that I wish I had known back before I started writing all that code that there was a better way to do it, a way that was going to be so much more productive that even throwing away months of work was going to be sort of OK.

So what is that better way?  Using CocosBuilder.

Cocos2D is a powerful API for building your games on iOS, but it is just code, and when I started out on my game I quickly found it impossible to organise all the resources I needed and to size and position all the elements on the game screen.  As I mention in the video I had seen CocosBuilder last year but it seemed flakey and not up to doing enough of what I needed.

But the new 3.0 version is much improved and there are a number of tricks with CocosBuilder that allow you to do a lot more with it than appears at first blush.  It turns out to be well-suited to creating an adventure game like mine, if you can figure out how to game it to your ends.

To try to help anyone who is contemplating going down the path I went down, or anyone who needs a powerful game interface creation tool but is too afraid to ask, here is a video tutorial I put together looking at how to get started with CocosBuilder for iOS.  The tutorial also includes a bit of my thinking around the game editor journey for me.

The tutorial comes in 4 parts, each of around 10 minutes (due to YouTube constraints) and I have tried to make the divisions not too arbitrary.  I'd encourage watching the whole thing, but if you just want to dip into the bits you need I hope the text below will help choose the right parts to watch.

As well as watching my tutorial please also check out two other great tutorials (not videos but very good nonetheless) which I used myself during my CocosBuilder learning process:
http://code.zynga.com/2012/10/creating-a-game-with-cocosbuilder/
http://www.raywenderlich.com/23996/introduction-to-cocosbuilder

Here are download links to the software I used:

• cocos2d-iphone-2.1-rc1.tar.gz
• Download CocosBuilder Application

Part 1 - Installation and Setup of a Tutorial project for Cocos2D-iOS & CocosBuilder

Part 2 - CocosBuilder resources and first Run of content

Part 3 - Creating a HUD layer CCB

Part 4 - Animating the HUD & making the buttons work

Things I had to leave out

The tutorial was already up to 40 minutes so I had to leave some things out.  Maybe I need to learn how to talk faster.  :-)

Using the UI elements: I imported some UI elements in a plist file in part 1, but never got time to use them.  But if you experiment you should have no trouble in seeing how to use these.  It's pretty much a case of drag and drop.  In some cases you need to use the "Sprite frame" selector in the properties panel on the right-hand-side of CocosBuilder.

Making a layer use the targeted touch handler: I recorded some footage on this, but had to remove it to get the tut down to a reasonable size.  The trick here is that most tutorials and references tell you to implement registerWithTouchHandler in your CCLayer subclass in order to get the kCCTouchesOneAtATime behaviour.

With that behaviour you can use

- (BOOL)ccTouchBegan:(UITouch *)touch withEvent:(UIEvent *)event
{
    CCLOG(@"%@::%@ - %@", NSStringFromClass([self class]), NSStringFromSelector(_cmd), touch);
    CGPoint location = [touch locationInView: [touch view]];
    location = [[CCDirector sharedDirector] convertToGL:location];
    
    BOOL isHandled = NO;
    if (CGRectContainsPoint([self boundingBox], location))
    {
        isHandled = YES;
        // do stuff
    }
    return isHandled;
}

Now it turns out that you can get that by setting the following in CocosBuilder for your CCLayer subclass:

...and since these are set in didLoadFromCCB before the onEnter handler sets up the registration, this will cause the CCLayer's implementation of registerWithTouchHandler to set up your instance for one-at-a-time touches.  Now you can implement your touch handler (as above) and off you go.

Thanks for watching videos - I hope they're useful.  Please - if you spot any mistakes let me know so I can address them.

Happy Cocos building!