Introduction to CocosBuilder

Look Ma, No Code!

You’ll start off the re-imagined Cat Jump by creating the game’s Main Menu. This scene will have three buttons:

• Play – This will launch the game!
• Options – This will show an Options scene where users can select the game’s difficulty level.
• About – This will show an About scene that instructs users how to play the game.

The first thing you need to do is delete the HelloCocosBuilder.ccb file, since that’s just a default file created by CocosBuilder.

Note: You would think it should be fairly straightforward to delete an unused scene file from a CocosBuilder project, but I wasn’t able to do this directly. I had to resort to closing CocosBuilder, deleting HelloCocosBuilder.ccb via Finder, and then reopening the project in CocosBuilder. If anyone has knows an easier way to do this, please comment in the forums!

Next, go to File\New\New File. This will open a dropdown menu. Make sure the Root object type is CCLayer, and select iPhone Landscape and iPhone 5 Landscape from the options given.

When you’re done, press Create, name the file MainMenuScene and save it in your Scenes folder.

The project pane should now look something like this:

And with that, you’ve created your first scene! Now how about adding some sprites?

Click the CCSprite button on the toolbar. Hint: It’s the one circled in the image below. :]

This will add a new sprite to the scene.

Select the new sprite and set its frame to Title_catjump.png. You can use the right sidebar, which has the properties of the currently selected item, to do this. Use the Sprite frame property in the CCSprite section, and navigate the dropdown to select Title_catjump.png under Resources\Normal.

Next, center the sprite by simply dragging it to the center position. Or, if you’d rather be exact, you can set the Anchor Point (under the CCNode section) on the right sidebar to 0 for both X and Y values.

Note that this will only work if you have the Position set to be the bottom-left corner. If you change the position, then you’ll have to set the X and Y values accordingly. Have some fun – see what happens when you try different values. :]

Great! You now have your background image all set. The next thing to do is add buttons for the menu items.

Tap the CCControlButton toolbar item to create a new button on the screen.

The new button comes with a nice background image, which you can find in the ccbResources folder that CocosBuilder created. Set the title of this button to Play via the CCControlButton section on the right sidebar, which includes a Title property.

Adjust the position of the button. You can place it anywhere you like by dragging it, or set an absolute position using the right sidebar.

OK then, more buttons! Repeat the above process to add two more. Set the title for the first one to Options and the second to About. Your final layout should be similar to the one shown in the image below:

Hurray, the layout for the first screen is now complete!

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: