Introduction to CocosBuilder

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!

Difficult Is Not An Option!

Like the Main Menu, the Options scene will have three buttons, and creating this scene will be just as painless.

In the case of the Options scene, the buttons will allow the user to select a difficulty level of Easy, Medium or Hard. There will also be a back button to return to the Main Menu.

Open CocosBuilder and create the new scene by selecting File\New\New File (follow the same steps as when you created the MainMenuScene), name it OptionsScene and save it in the Scenes directory.

Add three buttons to the scene and set their titles to Easy, Medium, and Hard. Then set their tags as 1, 2, and 3, respectively.

To get events when the user taps these buttons, you need to register a method to be called. Just as you did with MainMenuScene, set the selector for each of the buttons to difficultyButtonPressed: and the Target to Document Root.

Note: Wondering what Document Root means? It means the root node in the “Default Timeline” tree. Soon you will set the root node (CCLayer) to a custom class – OptionsLayer. That means that OptionsLayer will be the Document Root.

The layout should look something like this:

Now for that back button. This time, instead of adding a CCControlButton, add a CCMenu with the back button as a menu item.

Press the CCMenu button on the tool bar.

This will create a CCMenu node and add it to the OptionsScene layer. Now, add a CCMenuItemImage by pressing the CCMenuItemImage button on the tool bar.

Set the Normal and Selected sprites for this CCMenuItem as btn-back-0.png and btn-back-1.png. These properties can be set from the CCMenuItemImage subsection on the right pane.

Place the back button in the top-left corner of the scene and set the selector as backButtonPressed:. Don’t forget to set the Target as Document root.

That’s it! The scene should now look like this:

Just as you did with the MainMenuScene, add a custom class for the OptionsScene. Name it OptionsLayer.

As before, save your changes, publish the scene, and add the CCBI file to the Xcode project.

Switch to Xcode, create a new class under the Layers group and name it OptionsLayer (make sure it extends CCLayer) – just as you did before.

Next, add the following import and declare statements to the top of OptionsLayer.m:

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

#define DIFFICULTY_EASY_BUTTON_TAG 1
#define DIFFICULTY_MEDIUM_BUTTON_TAG 2
#define DIFFICULTY_HARD_BUTTON_TAG 3

Also add the following methods:

-(void)backButtonPressed:(id)sender {
    [[CCDirector sharedDirector] replaceScene:[CCTransitionFlipAngular transitionWithDuration:1.0 scene:[CCBReader sceneWithNodeGraphFromFile:@"MainMenuScene.ccbi"]]];
}

-(void)difficultyButtonPressed:(id)sender {
    CCControlButton *button = (CCControlButton*) sender;
    NSString *difficultyLevel = @"Hard";
    if (button.tag == DIFFICULTY_EASY_BUTTON_TAG) {
        difficultyLevel = @"Easy";
    } else if(button.tag == DIFFICULTY_MEDIUM_BUTTON_TAG) {
        difficultyLevel = @"Medium";
    }
    NSLog(@"Difficulty is set to %@", difficultyLevel);
}

All of this should be familiar to you by now. :] backButtonPressed: will take the user back to the Main Menu scene.

difficultyButtonPressed: in its current form doesn’t actually set a difficulty level, but it will log the user’s selection. Feel free to implement the difficulty level for the game later, on your own – will you accept the challenge? :]

Build and run the game, and now you have two fully functional scenes. You’re halfway to a full game interface!