CocosBuilder is a free tool for graphically laying out sprites, layers and scenes for Cocos2D iPhone and Mac. It’s ideal for quickly and accurately creating menus and other parts of the interface, but can also be used to create levels, particle systems or any other kind of Cocos2D node graphs.
It’s super easy to include the scenes you build in CocosBuilder into your project. Add the CCBReader files, then load the node graph or scene with a single line of code!
CocosBuilder allows you to patch into the generated file at any point by automatically assigning variables and custom classes for the objects that you load through the CCBReader. Objects created by CocosBuilder also plays beautifully with your existing Cocos2D code.
Example usages
Load a CCScene from a CocosBuilder project:
CCScene* scene = [CCBReader sceneWithNodeGraphFromFile:@"example.ccb"];
Load a particle system (the root node of the ccb-file needs to be a CCParticleSystem):
CCParticleSystem* particles = (CCParticleSystem*)
[CCBReader nodeGraphFromFile:@"example-particles.ccb"];


May 23rd, 2011 on 9:42 pm
Great tool, will use it and let you know how it goes!!! Great!!! Keep up the good work.
May 24th, 2011 on 6:09 am
Great tool for cocos2d developers.
May 24th, 2011 on 1:31 pm
Hey man, great work… please keep on this good work! im sure it will save us some good time
May 24th, 2011 on 6:43 pm
Thank you for this great tool ! Keep up this good work. Put a donate button here to say thank you in this way
Dorald.
May 27th, 2011 on 12:31 pm
Thank you man! This is a Realy useful tool.
Don’t you want to open your sources under some license? I can help you to work with it!
May 29th, 2011 on 10:29 pm
Awesome tool. Could you make in 0.7 update possibility that when you click right mousbutton you get the Add object and Add object as child options? In the Structure window. Thanks.
May 30th, 2011 on 4:54 pm
CocosBuilder Rocks!! Thanks!!
Will this project be open sourced or designed to be a shareware?
Anyway as @Doraid said, put a DONATE button here!
June 1st, 2011 on 10:29 am
nice work this editor has many possibilities
however
at the moment it gets 0 for usability
dont think you need extra buttons to move around objects, you should be able to move sprites by a simple click and drag. also resize and rotate should be done with handles that appear once you hover an object like most design apps do! you should be able to add assets by drag and drop, currently it simply shows a list in current directory. Sprites should move with simple press of the arrow keys!
this app has huge potential but wont go anywhere far with such usability problems!!
June 1st, 2011 on 1:21 pm
Hi paris,
Thanks for your feedback! Currently you can nudge objects using cmd-arrows (or cmd-shift-arrows), similar to Photoshop.
The other issues are updates scheduled for version 0.7. CocosBuilder is still an unfinished beta, but I wanted to share it to get feedback and also because it’s already quite useful. I save hours every day using it.
December 19th, 2011 on 12:12 am
I have a suggestion to make for working with custom classes. You should, in theory, be able to add the ability to set custom properties. For example, if I synthesize properties or otherwise create setters in the format set{Property} you should be able to have maybe a table, or some interface similar to a .plist editor that lets you set these values on a custom class. Obviously, those would be limited to simple numbers, booleans and strings, but I think it would be a very useful addition.
The reason this comes up is because, for example, I have animated backgrounds for various scenes that take certain simple parameters (color, movement speed, etc). I currently add them to cocosbuilder scenes as a custom class and give them a tag by which I retrieve them later.
Just a suggestion, either way your this application kicks ass and thanks a lot for creating it!
December 22nd, 2011 on 8:16 pm
Hi Yuri. This is a very good suggestion, and one that I originally planned to include but didn’t have time to finish. It is possible that it will make it in future versions! Thanks!
June 2nd, 2011 on 10:07 pm
I want to like it, but i get 24 errors from the CCBReader file. Any help?
June 4th, 2011 on 8:40 am
There should be no errors or warnings when compiling the CCBReader. Which version of cocos2d-iphone are you using? Have you included both the .m and .h files in your project?
June 4th, 2011 on 11:12 pm
This is a fantastic tool! If this was the last version it would already be perfect because it saves me an unbelievable amount of time.
Thank you again for making this.
(I was this close to saying I love you lol)
June 8th, 2011 on 9:43 pm
This is a great tool, really very useful for us. Keep up the great work.
June 13th, 2011 on 10:58 am
Absolutely amazing tool. Really, really handy. I would like to congratulate you for this incredible work.
Only one question. Do you plan to include support for CCLabel objects?
Thank you very much for sharing this awesome tool.
June 13th, 2011 on 11:01 am
OMG! I had missed it! Support for CCLabelIBMFont is already included!!! You are GOD man!
Thanks and sorry for my confusion :p
June 13th, 2011 on 3:09 pm
Glad to hear that you like CocosBuilder and that you found the label-function.
Originally I tried to also include support for CCLabelTTF, but the support in for Cocos2D-mac for it was kind of buggy so I left it out for now. I hope to add it later too.
June 15th, 2011 on 10:21 pm
One little handy simple feature?
Where it lists the var associated if it’s not assigned but there’s a value maybe show it in red? That would remind me to assign it later..not big deal though just a nice little touch.
June 16th, 2011 on 8:47 am
Yes, this is a planned feature!
June 23rd, 2011 on 2:58 am
if have the shortcuts maybe cool.
June 24th, 2011 on 8:51 am
all the base are belong to us!
June 24th, 2011 on 9:01 pm
What is this template feature I see when creating a new project? This sounds like a great feature!
June 27th, 2011 on 6:55 pm
The template feature is currently only used for particle systems. You are right some sort of templates could be a valuable feature, and could possibly be added to future versions!
June 28th, 2011 on 12:52 am
How do you access the selected menu button? I need to be able to offset the selected image after it’s been pressed.
June 28th, 2011 on 5:36 am
The images for the states should be the same size. From the Cocos2D documentation:
“CCMenuItemImage accepts images as items. The images has 3 different states:
- unselected image
- selected image
- disabled image
For best results try that all images are of the same size”
That being said, if you really have to, you can access the sprites for the different states in your code.
June 29th, 2011 on 12:05 am
fyi for those trying to mess with the menuitem after clicking. Put the following in the selector of the button.
CCSprite* s = (CCSprite*)[sender selectedImage];
s.position = ccp(50,50)
June 29th, 2011 on 9:08 am
Hy, thanks for your work…
just a question… if i have a CCNode in my Layer… there is a way to set a key for any node? just for retrieve it…
for example… i have a ccmenu and every time the button is pressed… it change its image…
I should be use a index related to the node hierarchy in cocosbuilder? If i have a ccmenu with 3 ccmenuitem the 2° is the 2° children of menu?
Thanks
June 29th, 2011 on 9:12 am
Founded xD
in code connection -> Doc root var
thanks
July 10th, 2011 on 2:41 am
Hi!
I’m tomoyuki, and CocosBuilder user.
CocosBuilder is very very good!
But CCLabelTTF isn’t support.
It’s Important to me.
Do join I to programming?
Because I can programming.
July 11th, 2011 on 7:28 am
At first I tried to add support for CCLabelTTF, but currently the MacOS version of it is so buggy it causes CocosBuilder to crash and is also missing many features. When a stable version of CCLabelTTF is available for Mac I will add it to CocosBuilder!
July 15th, 2011 on 9:46 am
Hello,
After using intensively Cocosbuilder I have some new feedback for you. I think that this tool is extremely useful for developers but artists seems to doesn’t like it :-/
My artist says that he cannot work with it because cocosbuilder lacks of basic layout manipulation features such as: group alignment or snap to grid stuff.
Are you planning to include this kind of features?
Anyway I think this is a great tool :p
July 15th, 2011 on 11:30 am
Yes, these are planned features!
July 15th, 2011 on 12:26 pm
CCAnimation support would be also great :p
July 15th, 2011 on 12:27 pm
It was CCAction :p
July 16th, 2011 on 3:03 am
Can you provide tutorial/example code on how to use custom class in CocosBuilder ? Thank You ,it is a useful tool for cocos2d developer.
July 16th, 2011 on 8:14 am
There is an example included, it uses a custom class for a CCLayer.
July 18th, 2011 on 1:42 pm
Just a small note, in my version (1.0) custom classes wasn’t supported for CCSprite and CCMenuItemImage but I added code to handle that in CCBReader.
In order to get it to work I had to uncomment the
if (extraProps) customClass = NULL
line. Everything seems to work as it should now.
Anyway, so far cocosbuilder looks good! Keep up the great work
July 19th, 2011 on 12:24 am
I think I found a bug
I have a scene with buttons. when I click the button it replaces itself with another scene.
On the next scene, even though the previous scenes button isn’t there, it is still being triggered ( tries to find the selector which isn’t there)
Program received signal: “EXC_BAD_ACCESS”.
I tested this by move the button to a different location. Anywhere I put the button, if i click in that location on the next scene, it crashes.
July 19th, 2011 on 12:39 am
Here’s the fix
- (void)onExit
{
[[CCTouchDispatcher sharedDispatcher] removeDelegate:self];
[super onExit];
}
July 21st, 2011 on 2:48 pm
I got a problem with Lion.
Can open old file it keeps restart application.
Or Display blank CCSprite.
December 8th, 2011 on 9:33 am
I had a similar problem with OS X Lion, by doing the following it worked.
Just right click on “CocosBuilder.app” select “Get Info” and check the option “Open in 32-bit mode”
Thank you Viktor for the great tool.
December 22nd, 2011 on 8:17 pm
Thanks for the information!
August 1st, 2011 on 8:04 am
Thx for your job Viktor, it was too late for us to build a UI pipeline around CocosBuilder, but we plan to do it in our next project.
By the way, for people developping in C++ with Xcode, do you plan to do a version of cocosBuilder to support cocos2D-x ? From what I understand, it would consist in rewrite CCBReader.
September 10th, 2011 on 8:40 am
Hey Vikto,
great tool, we are using it and we have made a donation to support your efforts!
We may have a bug.
Using Texture Packer to create sprite sheets.
Bit Depth – set on the sprite sheet is RGB8888
sprites are rendering fine..
but menuItemImage is rendering with white edges
same asset as a sprite – fine
same asset as a sprite – as menuItemImage – white edge
is there a reason a menuItemImage would be at a different bit depth, even when it is sourced from the same sprite sheet?
September 10th, 2011 on 8:48 am
sorry just to add… file format is pvr.ccz
September 14th, 2011 on 2:52 pm
I was thinking it would be useful to be able to “solo” an item in builder.. so you could click on something… and have it be the only thing visible..
like when you solo a track on a mixing board to hear what it is..
lots of times I am updating images in a lrg ccb file..
this would be very helpful
thanks!
December 22nd, 2011 on 8:29 pm
Thanks for your suggestion!
September 17th, 2011 on 6:08 pm
Yesterday on the cocos2d-x forum someone posted a C++ version of cocosbuilder and the CCBReader.
http://www.cocos2d-x.org/boards/6/topics/3595
September 18th, 2011 on 8:05 pm
Hey, great app but I think you would get much more traction if you had an export ability. Meaning, if you could export the results of the builder’s UI into whatever main code was asked for such as a CCLayer, your app would probably be quite the hit.
I know you have background code that translates your xml into what is needed to build but many of us like to have complete control of our code and having the ability to manipulate how things work that just is not available w/ your ccb.
An export into .m or .mm would make this utility much more useful because as of right now I am just using this app to lay my UIs out and then once I get all of the coordinates I actually code the placements into my existing framework. In other words, I cannot utilize your ccb as its too restrictive.
Please take this as constructive because Cocos2d users REALLY need something like this.
Thanks!
PAR
September 19th, 2011 on 3:40 am
Actually, as I look at your code, is the “ccObjectFromDictionary()” method what I’m asking? I wish you had a bit more documentation as to what each of your methods are
PAR
December 22nd, 2011 on 8:25 pm
Hi. I use the same CCBReader inside CocosBuilder, so this function is for internal use only. That is why it hasn’t been documented.
December 22nd, 2011 on 8:27 pm
I saw someone who had written a perl script that does this. Personally I prefer having the code separate from the ccb-files as it makes it possible to go back and edit the files. But if many people requests this it is possible that it will be added in future versions.
September 19th, 2011 on 8:43 am
I found this great tool on cocos2d forum
By my test, everything looks well but reopen the saved file.
When i open a saved *.ccb file, cocosbuilder start but displays nothing,I also tried open files from “file” menu and “open recent” menu, both are not works.
Is there any solution?Thakns
September 19th, 2011 on 8:50 am
I found this way works:
close all cocosbuilder instances => start =>”open” saved project
October 24th, 2011 on 12:52 pm
Is it possible to add custom properties to the nodes?
December 22nd, 2011 on 8:22 pm
Hi Alex. At the moment this is not possible.
October 30th, 2011 on 7:40 am
The tool is great for iPhone development. But what can we use it to develop games for iPad ??
Thanks
December 22nd, 2011 on 8:22 pm
Hi Jerry, there should be no difference in using this tool for iPhone or iPad development.
December 2nd, 2011 on 3:19 pm
Man, i pay to support cocosbuilder and you don’t reply the emails!
Since you release the version 1 (not stable) you don’t do anything for the program, this is not good, I feel robbed.
December 22nd, 2011 on 8:21 pm
Hi Juan. I am sorry that I’ve been slow in replying! I have not been able to work on CocosBuilder for a while, but it looks like that will change in the not too distant future.
December 6th, 2011 on 7:30 pm
Florent:
Hello,
version for Cocos2D-x already exist. Check this link.
http://www.cocos2d-x.org/boards/6/topics/3595?r=5721
MG
December 22nd, 2011 on 8:19 pm
Thanks for sharing! Great work!
January 9th, 2012 on 2:56 pm
There is no way to create another object root in the same project ?
This will help a lot to work in one archive.
Thanks
January 9th, 2012 on 4:11 pm
Sorry, currently this is not possible.
January 27th, 2012 on 12:26 pm
hello vik,
nice app…
if it possible to use CCLabelTTF with the current version 1.0?
hope that you can support it also.
also do you have a plan on implementing spritesheets/spriteatlas with the app?
i suggest like reading the plist of the spritesheets of the ones generated from texturepacker or zwoptex.
thanks and your app rocks!!!!!
February 10th, 2012 on 8:05 pm
There will be support for CCLabelTTF soon. There is already support for spritesheets in the current version of CocosBuilder.
January 31st, 2012 on 4:28 am
Will there be support for CCActions as well, sometime in the future?
February 10th, 2012 on 8:04 pm
I hope to add support for CCActions in the future. I will be working on the roadmap for CocosBuilder next week and hope to give you more updates soon!
February 28th, 2012 on 2:36 am
Love It! I hope to see support for adding custom classes as well as CCLabelTTF. Will you be open sourcing the project? I’m sure many of us would gladly contribute if you do.
February 28th, 2012 on 8:05 am
I recognize the need of making CocosBuilder open source, and I am looking into it! Hope to include CCLabelTTF too.
March 5th, 2012 on 10:27 am
I think I found a bug, i cannot select “-hd” images for my sprites, i don’t see them in the list of files at all.
March 5th, 2012 on 2:19 pm
This isn’t a bug, it’s a feature. The idea is that you use the regular sprite, cocos2d will automatically choose the hd image when the ccb is loaded in your app.
March 7th, 2012 on 8:17 am
Yes, but in my case I want to use the “-hd” versions for the iPad ccb file and it is not possible, I have to create a third file (for example named “-ipad”) and use that file, or I have to hard code the sprite file names in my code so that the iPad loads the bigger files.
March 13th, 2012 on 3:05 pm
Great tool! Speeding up development a ton!
Any plans on adding batchnode support? As in – if you use a spritesheet in CocosBuilder, you can tell Cocos2d to use that spritesheet as a batchnode and any sprites added from that spritesheet are rendered in a batchnode.
March 23rd, 2012 on 12:47 am
How do you add images to the project
March 23rd, 2012 on 2:24 pm
You put the images in the same folder as the ccb-file. If they do not show up, try restarting CocosBuilder. There are still some issues with the resource handling.
March 23rd, 2012 on 3:19 am
Thanks for sharing this tool.
I has a question about using plist file. I knew that when I add a sprite there is a “Sprite sheet” option. In this option I think I can choose *.plist file. But in fact I can’t change this option. Can you do me a favor to tell me how to do that? Thanks again.
March 23rd, 2012 on 2:26 pm
Sorry, I am not sure I understand your question, can you try to explain a bit further?
March 24th, 2012 on 9:41 am
The question is just how to add a sprite with *.plist file.
March 24th, 2012 on 10:10 am
Just drop the sprite sheet and its companion image in the same folder as the ccb. It should show up as a folder in the resource manager.
March 26th, 2012 on 1:43 am
I have done that. But I can’t see the sprite sheet(*.plist file) in the resource manager, just its companion image.
March 24th, 2012 on 5:47 am
Love Cocosbuilder!! But I can’t get the hd version of images from a plist to show up properly. When I use it, it shows up fine in cocosbuilder. But when I run it on my device or simulator, it doesnt work. Any suggestions?
March 24th, 2012 on 5:56 am
Hey,it’s a great work! Thank you!
There’s a problem when handling touch event with the sprite.I add a sprite in the cocosBuilder as a custom class.Then I overwrite the – (BOOL)ccTouchBegan method, but I find I can’t use [self runAction:] in this sprite class after that.
I delete all the touch handling methods,then [self runAction:] works again.
March 24th, 2012 on 10:09 am
It’s hard to understand what your problem is without seeing your code, but the member variables are set after the init method has been called. So if you need to set actions etc you should do so in the didLoadFromCCB method.
March 26th, 2012 on 1:42 am
I have done that. But I can’t see the sprite sheet(*.plist file) in the resource manager, just its companion image.
March 26th, 2012 on 5:58 am
Which program are you using to create the sprite sheet?
March 29th, 2012 on 6:56 am
Zwoptex
March 28th, 2012 on 3:34 am
Does CocosBuilder only support cocos2d 2.0?
Now I’m using the 1.1beta, but I found CCMenu and CCMenuItem are not working for cocos2d v1.1beta2..
And can you add more fonts for CCLabelTTF?
March 28th, 2012 on 4:10 pm
CocosBuilder is cocos2d 2.0 only, I think some features would need to be added from the gles20 branch to make it work with cocos2d 1. The support for CCLabelTTF has been greatly improved in the latest version (on GitHub)
March 31st, 2012 on 2:38 am
I think cocos builder will be more popular if it supports cocos2d 1.x since there are more apps developed by it.
Maybe CCMenu and CCMenuItem are the main problem with cocos2d 1. I looked into your source code ,init method are not supported.
March 28th, 2012 on 6:09 pm
Wowzeres. Awesome work!! This is going to save so much time! I’d like to write a tutorial to use this. If I did, and it isn’t that bad, would you consider posting it here? I think it’d help some people (including myself if I had it to do over) get use to the tool.
March 29th, 2012 on 9:44 pm
Yes, that would be awesome!
You may want to use the latest version from GitHub, or wait a few days until I release the next beta version.
April 6th, 2012 on 6:07 pm
Great thanks for developers!
Could you advice what the problem with loading the CCMenuItemImage. I added 2 images for normal and selected states but selected is now working.
April 7th, 2012 on 4:33 pm
Have you tried the example file? Does it work for you?
April 11th, 2012 on 12:58 pm
Great program!
But I was hoping to use this for help with Box2d, but I can’t seem to figure it out.
I’m stuck on how to attach the sprites from the CCB file to Box2d bodies.
In simpler terms, how do I get CCSprites from the CCB file to put in CCSprite variables?
Thanks!
April 12th, 2012 on 7:08 pm
I think that the best way to do this is to create a plug-in for your box2d bodies.
April 13th, 2012 on 12:11 am
How’s the best way to go about doing this?
April 19th, 2012 on 10:10 am
The sptite sheets are not loaded as assets. I put the .plist file in the same folder and it doen’t shown in builder. How resolve it?
April 22nd, 2012 on 11:41 pm
Is there a video on how to implement this into my application?
May 3rd, 2012 on 10:10 pm
Not yet
May 3rd, 2012 on 12:22 pm
Cool work!
I have a suggestion. It includes image from the same folder only, Instead it should support to include image from a source path.
May 3rd, 2012 on 10:08 pm
This is an existing feature: https://github.com/cocos2d/CocosBuilder/blob/develop/Documentation/1.%20User%20Guide.md (Using multiple resource directories). It’s on the roadmap to rework it so it will be easier to use though!
May 4th, 2012 on 10:27 am
Hello,
It is a documented requirement that all assets be in the same directory as the builder file, but it seems that there is an implicit requirement that all assets be at the root of the bundle. At the moment, in preparation for in app purchases of levels, I have added the builder file and associated resource files into a subdirectory of the main bundle. Unfortunately, the file loading routines in cocos cannot find the .fnt file for instance, since it looks in the root of the bundle. I could modify the .ccb file by hand to include the relative path (e.g. sandbox/builder/blah.fnt) but since I cannot modify this via the editor, I cannot include this change in the published version of the builder file. Would it be possible to add a subdirectory string within the builder app for the project resources to indicate the directory offset from the root of the bundle? That would be great!
May 4th, 2012 on 10:41 am
Just an idea… perhaps the subdirectory string could be extracted and cached when the builder file is loaded via:
[CCBReader sceneWithNodeGraphFromFile:@"sandbox/builder/blah.ccbi"]
This would be flexible and require no changes to the builder app interface.
May 9th, 2012 on 9:18 pm
I am currently rewriting the way CocosBuilder is loading resources, including having extra resource directories etc.
May 4th, 2012 on 2:28 pm
additionally, maybe I’ve missed something, but the ability to set the ‘z’ order on child nodes within the builder app would be extremely helpful. Retrieving them by tag then resetting them in didLoadFromCCB is a bit awkward.
May 9th, 2012 on 9:17 pm
zOrder is set by how you order your nodes in CocosBuilder, it cannot be set directly.
May 14th, 2012 on 12:04 pm
The case I am dealing with is that i insert a layer “below” the layers I’ve created in the builder in didLoadFromCCB, requiring me to either place all of my new elements in negative z, or call reorderChild: on the layers I created in the builder, referenced by tag. If I could set explicit z-values in the builder, there would be no need for a reordering on load; I could reserve certain z-values for various elements (tile map, UI, etc.)
May 5th, 2012 on 8:35 am
My multiline CCLabelTTF only shows the first line when run on device. Why.
May 5th, 2012 on 8:48 am
nevermind
May 6th, 2012 on 2:03 pm
Just testing it out, but it might be interesting to take a look at: https://github.com/jerrodputman/CCKit
It offers some nice extensions (CCScrollLayer, CCTableLayer, CCNavigationController, and CCGestureRecognizer) that might be interesting for cocosbuilder.
May 9th, 2012 on 9:16 pm
Thank you! Will check it out!
May 14th, 2012 on 12:05 pm
CCNode+SFGestureRecognizers for cocos2d: http://merowing.info is not quite as broad in scope, but easier to build in; maybe a better example.