Introduction to CocosBuilder

This is a blog post by iOS Tutorial Team member Ali Hafizji, an iOS and Android developer working at Tavisca Solutions. CocosBuilder is a free Interface Builder-like tool for Cocos2D that allows you to quickly and easily layout the sprites, layers, and scenes for your game. CocosBuilder is ideal for quickly laying out menus and […] By Ali Hafizji.

Leave a rating/review
Save for later

Learn how to use CocosBuilder – an Interface-Builder like tool for Cocos2D!

Learn how to use CocosBuilder - an Interface-Builder like tool for Cocos2D!

This is a blog post by iOS Tutorial Team member Ali Hafizji, an iOS and Android developer working at Tavisca Solutions.

CocosBuilder is a free Interface Builder-like tool for Cocos2D that allows you to quickly and easily layout the sprites, layers, and scenes for your game.

CocosBuilder is ideal for quickly laying out menus and other game interface scenes, where it would be a pain to have to place all of the elements manually.

Before CocosBuilder, creating even a basic interface for a game in Cocos2D was a pain in the butt. When adding a menu or button into your game, you’d usually do something like this:

  • Make a guess. “Uhh, yeah I think the button should be at about 50×50.”
  • Build and run. “Oops, that’s not quite right!”
  • Tweak the guess. “I think 60×50 would be better!”
  • Rinse and repeat. “Doh, still not right. Gahh!”

CocosBuilder eliminates all of these steps, including the multiple iterations of setting and testing sprite positions. This frees you to focus on the game logic rather than pulling your hair out over the interface, making you more productive as a developer – which is always a good thing, right? :]

This beginning-level tutorial will show you how to use CocosBuilder to create simple interfaces. You’ll learn how to set up menus, buttons, particle systems, basic level layouts, and connect the interfaces you make to code!

You’ll recreate the Cat Jump game originally developed for Ray and Rod’s Cocos2D via Minigames workshop. Of course, this time around, there will be a lot less coding. :] You’ll see how that CocosBuilder will save you a ton of time and code!

This tutorial assumes you have some basic familiarity with Cocos2D. If you are new to Cocos2D, check out some of the other Cocos2D tutorials on this site first.

Let’s build some interfaces, the easy way!

Introducing Cat Jump!

Cat Jump is a game about a cat having a bad day. He’s just minding his own business, walking along the street, when all of a sudden everyone’s out to run him over – cars, trucks, even kids on tricycles!

Here is a preview of the game in action:

Your poor cat only has a limited number of lives (9 of course!), and your goal is to stay alive as long as possible by dodging the obstacles.

To get a preview of the game you’ll be making, download this version of CatJump made without CocosBuilder. Open it in Xcode, build and run, and play the game for a while – it’s a lot of fun!

After playing the game a bit, peek through the code – you’ll notice a ton of hardcoded offsets to set up positions for menus, labels, and sprites. Those were a pain to set up – you’ll learn a better way!

In this tutorial, you will recreate Cat Jump by performing the following tasks:

  • Remake the Main Menu scene in CocosBuilder. Right now the Main Menu layout is done by placing items with hardcoded offsets – you’ll delete all that code and use CocosBuilder instead!
  • Add an Options scene. You’ll add a new Options scene with three buttons for difficulty level: Easy, Medium, and Hard. Tapping on any option will invoke a selector in your code.
  • Add an About scene. You’ll also add an About page with a small particle system (in other words, a cool special effect). Using CocosBuilder, you will not write a single line of code to do this!
  • Rebuild the Game Scene using CocosBuilder. You’ll remove manual sprite placement and use CocosBuilder to help you out instead!
  • Rebuild the Game Over Scene using CocosBuilder. Again, no more hardcoded offsets! :]

Finally, you’ll learn some handy troubleshooting tips for how to prevent and resolve common problems with CocosBuilder. Not that CocosBuilder is error-prone, but there are always a few obstacles to dodge, kinda like kids on tricycles! You’ll put them on your radar now, saving you time later.

Getting Started With CocosBuilder

If you haven’t already, download CocosBuilder by visiting the CocosBuilder website and selecting the Downloads tab. Make sure to get the latest version, which at the time of writing is 2.1. While you’re at it, download the Examples file as well.

Extract the CocosBuilder application from the archive and copy it to the Applications folder (as usual for an app installation).

Before you create a new project in CocosBuilder, you need to create a directory for your project. This is the place where you will store all the game resources/assets.

Note: You can also create a project and reference resources wherever they may currently reside on your hard drive, but find creating a directory structure like this helps me know where all my files are and keep things organized.

Create a new directory on the Desktop and name it CocosBuilderFiles. Then create two subfolders within this directory and name them Resources and Scenes.

The Resources folder will, obviously, contain all the resources for the game (spritesheets, fonts, etc.). If you want, you can copy all of the resources from the Cat Jump project you downloaded earlier, but to make things simpler I have created a ZIP file with everything you need. Download it, extract it and copy its contents to the Resources folder.

Fire up CocosBuilder and select File\New\New Project from the menu. Name the project CatJump and save it in the CocosBuilderFiles directory.

Now that you’ve created the project, you’ll see the Resources and Scenes folders in the Project sidebar on the left in CocosBuilder. Also notice that CocosBuilder automatically created a new folder called ccbResources. Along with that, you will see a new file called HelloCocosBuilder.ccb. Double-click the file to see its contents.

It’s a very basic layout with a label that says “Hello CocosBuilder”:

Don’t worry, your Cat Jump interface will be a little more complicated than that. :]

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!

Ali Hafizji


Ali Hafizji


Over 300 content creators. Join our team.