Introduction to CocosBuilder

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