Introduction to CocosBuilder

Hooking up a Layer to a Class

Before you proceed, you need to make a few adjustments. Whenever you set up a scene using a layer created in CocosBuilder, if you want the scene’s layer to be a custom class, you need to tell CocosBuilder the name of that class.

For example, if you initialize a scene using the MainMenuScene file and you want its layer to be a class that you create, then you need to specify the name of that class in the Code Connections section of CocosBuilder.

Select the MainMenuScene.ccb file and select the CCLayer root node from the timeline.

In the Code Connections section on the right, set the Custom class textbox to MainMenuLayer. Now when you initialize this scene, CocosBuilder will look for a class named MainMenuLayer and use it to instantiate the scene’s layer.

Next you need to publish the CocosBuilder interface file. To do this, simply go to the File menu and select Publish. This will save a new file named MainMenuScene.ccbi to the Scenes directory.

Enough with CocosBuilder for now – it’s time to try this out in a Cocos2D project!

Time for Code!

First, make sure you have the latest version of Cocos2D 2.X installed – 2.1-beta4 at the time of writing this tutorial.

Then start up Xcode and create a new project with the iOS\cocos2d v2.x\cocos2d iOS template. Enter CatJump as the Product Name, enter the Company Identifier you used when creating your App ID, and set Device Family to iPhone:

Finish creating the project and save it somewhere on your hard drive.

Next, create a new group under the project root called Scenes, and drag and drop the CCBI file from the scenes directory into this group. Make sure the “Copy items to destination group’s folder (if needed)” is checked, and that the CatJump target is selected under “Add to targets.”

You now need to add CCBReader to your project. CCBReader is bundled with the example files you downloaded earlier from the CocosBuilder website. Extract the example files archive (if you hadn’t already) to a location on your hard drive. Find the CCBReader folder under Add to Your Project\cocos2d-iphone.

Drag the complete CCBReader folder to your project. Make sure that “Create groups for any added folders” is selected and that “Copy items into destination group’s folder” is checked. Do the same with the CCControlExtension folder.

Next, create a new group under CatJump and name it Layers. Create a new file with the iOS\cocos2d v2.x\CCNode class template under this group. Make it a subclass of CCLayer and name it MainMenuLayer.m.

Before you write any code, open AppDelegate.m and add the following import statement (at the top below the existing #import statements):

#import "CCBReader.h"

Next, open application: didFinishLaunchingWithOptions: and find this line:

[director runWithScene: [IntroLayer scene]];

Once you find that line, replace it with the following:

[director runWithScene: [CCBReader sceneWithNodeGraphFromFile:@"MainMenuScene.ccbi"]];

And that’s all the code you need in order to run a scene created with CocosBuilder! The CCBReader class will parse the MainMenuScene.ccbi file and create the scene for you!

But before you can run the application, there’s one final step. :] Remember the background image you added to your scene and the button images from the ccbResources folder in your CocosBuilder project folder?

Those images aren’t in your project yet, and you need them in order for the app to function properly. Otherwise, the app will crash. (In fact, you can test this right now by trying to run the app…)

From your CocosBuilder project folder, select all the files in the Resources folder and drag-and-drop them into the Resources folder in your Xcode project. Do the same with all the files in the ccbResources folder. As before, ensure that the “Copy items into destination group’s folder” is checked, that “Create groups for any added folders” is selected, and that the CatJump target is selected.

Now, build the app. If you get an error while compiling CCBReader.m, replace the line with the error with the following:

return [_bundle pathForResource:resource ofType:ext inDirectory:subpath];

Then run the app. When the app starts, you should see the Main Menu with the three buttons, as shown below:

The Main Event

Congrats, you now have a working layout made with CocosBuilder, with only one line of code! :]

But how on earth are you going to get events when the user taps on any one of those buttons?

Actually, CocosBuilder makes this task very easy! It allows you to specify the name of the method to invoke when the user taps a button. You can also specify the event for which the method will be invoked (via a checkbox).

Let’s add this functionality to MainMenuScene. Open MainMenuScene.ccb using CocosBuilder and select the Play button. Set its Tag property to 1 via the CCNode subsection in the right side pane.

Next, go to the CCControl subsection and fill the Selector textbox with the name of the method that will be invoked, buttonPressed:. Also set the Target as Document root (again, to hook it up to the layer).

Do the same for the other two buttons, but with different tags – set the Tag property of the Options button to 2, and the About button to 3.

Awesome! You have wired your buttons to call a selector present in the CCLayer. Save your changes, publish MainMenuScene.ccb again, and copy the published file to the Xcode project folder.

Note: You will not be able to drag-and-drop the file onto the Xcode project as before, since the file already exists in the project. So either delete the file from the project first, or drag-and-drop the new file via Finder.

Next open MainMenuLayer.m in Xcode and add the following import statements:

#import "CCControlButton.h"
#import "CCBReader.h"

Also add the following #defines for a few constants right below the #import statements. These refer to the tags for each of the three buttons you placed on the scene:

#define PLAY_BUTTON_TAG 1
#define OPTIONS_BUTTON_TAG 2
#define ABOUT_BUTTON_TAG 3

Now what about that buttonPressed: method? Add it to MainMenuLayer.m:

-(void)buttonPressed:(id)sender {
    CCControlButton *button = (CCControlButton*) sender;
    switch (button.tag) {
        case PLAY_BUTTON_TAG:
            [[CCDirector sharedDirector] replaceScene:[CCTransitionCrossFade transitionWithDuration:1.0 scene:[CCBReader sceneWithNodeGraphFromFile:@"GameScene.ccbi"]]];
            break;
        case OPTIONS_BUTTON_TAG:
            [[CCDirector sharedDirector] replaceScene:[CCTransitionFlipAngular transitionWithDuration:1.0 scene:[CCBReader sceneWithNodeGraphFromFile:@"OptionsScene.ccbi"]]];
            break;
        case ABOUT_BUTTON_TAG:
            [[CCDirector sharedDirector] replaceScene:[CCTransitionCrossFade transitionWithDuration:1.0 scene:[CCBReader sceneWithNodeGraphFromFile:@"AboutScene.ccbi"]]];
            break;
    }
}

This method is self-explanatory: all it does is handle each button tap separately. For example, when the About button is tapped, the About Scene is displayed.

Build and run the game. You should now have a completely functional Main Menu scene, like the one shown below:

Awesome, you have just created your first scene and you hardly wrote any code for it. :]

Of course, you might have noticed that the code for buttonPressed: refers to several CCBI files that you haven’t created yet. Hence, tapping on any of the buttons on the Main Menu crashes the game, since those scenes are not in place yet.

That’s what you’re going to do next – fill in the gaps!