Cocosbuilder 3 and XCode

This is the same as post we made on the cocos forums here, but we found we can’t edit the original post after a few hours, so probably better to keep this one up to date, add images and so forth. Hope it helps other people.

Intro/preamble/history

Cocosbuilder and cocos2d-js (javascript) are pretty interesting. They promise a free, open-source flash replacement that can publish to html5 and iOS, and via the c++ based cocos2d-x, to just about any other major platform (android and windows being the obvious ones). They’re being developed by Zynga, they made a little game called Farmville, maybe you’ve heard of it?

Cocosbuilder is aiming to be a flash-style authoring environment, with timeline, keyframes, resource navigator, code editor, publishing tool all built in.

Cocos2d-js is a javascript based scripting language that lets you do all your game logic in a runtime language, but all the high performance low-level stuff is pushed to native run-time engines. Not surprisingly, its the scripting language used within Cocosbuilder.

Cocosbuilder has been around for about a year or so, previous versions were only for layout and animation. You’d then take those cocosbuilder assets, load them into your xcode project, and do your game logic in obj-c.

Version 3 alpha 3 came out in March 2013, its big feature being javascript integration, so that you can do all your work in a unified, fast to prototype environment, and publish to other platforms as required. You can test your code in an almost live setting by sendign your game to a browser, or use the bundled cocosplayer app, and test it directly on an iOS device. Its great.

Right now however (April 2013), its still very bleeding edge, and not well documented. Ray Wenderlich has tutorials for cocosbulder v2 and xcode, and cocos-html5 and xcode (scroll down to the ‘just one more thing’ section), and there’s some handy posts on Zynga’s blog, but there’s not much around yet for cocosbuilder v3 AND javascript AND xcode. Getting cocosplayer to work wasn’t too bad, as we explained in this forum post, but getting a cocosbuilder game to a complete xcode compiled iOS app was a little trickier, thats what this blog post is about. There’s still some unanswered questions, we’ll get to those at the bottom.

Should note that this is also based on trawling quite a few posts from the cocos forums and stackoverflow, thanks for sharing everyone. 🙂

Setup

Publish Cocosbuilder Files

Similar to the difference between a .fla and a .swf, you need to publish the made-for-editing files (.cbb) into a compressed file format (.cbbi), as well as the rest of the stucture for your images, code, sounds.

  1. open cocosbuilder
  2. open the cocosdragonjs example
  3. file -> publish settings, disable all except iOS, set options to flat file export (you don’t need to do this, but saves a few extra folders being made which you don’t need right now)
  4. file -> publish. this creates a subfolder called ‘published files iOS’ with the compiled cbbi files and graphics in sub-subfolders.

Setup Xcode project

  1. in xcode, file -> new project, ‘cocos2d ios with javascript’, name it, choose a folder
  2. remove ‘main.js’ from the project navigator, you’ll be replacing it with one from cocosbuilder.

Copy Cocosbuilder resources to Xcode

  1. In finder, select everything in the published files iOS folder, copy
  2. Find the resources folder of your xcode project, paste
  3. Select them all in Finder, drag them into the xcode project navigator under the ‘resources’ folder
  4. In the dialog that appears, I enabled ‘copy items into destination folder’ and ‘create groups for any added folders’, and ticked ‘add to targets’.

Modify Xcode project

You need to include the ccb reader headers (easy), and tell xcode to copy the js files, not try and compile them (easy once you know where to look)

  1. edit ‘AppDelegate.h’, and add the include required to load ccbi files:
    #include "CCBReader.h"
  2. select the topmost entry of your project navigator, blue icon, should be named the same as your project
  3. in the main panel, swap to ‘build phases’
  4. in the filter entry, type in ‘.js’
  5. you’ll see that xcode has mistakenly put the cocosbuilder .js files into the ‘compile sources’ category. that’s bad. select all the .js files that are in that section, and drag them into the ‘copy bundle resources’ section instead. if you don’t do this, you’ll get lots of ‘foo.js: file not found’ style errors.

That should be it, hit Run and admire your handiwork!

Issues

Ok, so there’s some broken things.

  • It’s in landscape rather than portrait
  • Graphics are messed up.

Fixing orientation

The xcode cocos template is set to landscape by default. Easily fixed:

  1. Go to the target settings panel (select the top icon in the project navigator, then the summary pane)
  2. Set the app to universal (may as well, the cocosbuilder project is designed to handle iphone, ipad and retina displays)
  3. Set the orientation for iphone to portrait only, scroll down, do the same for ipad
  4. In AppDelegate.mm, search for ‘Landscape’, replace with ‘Portrait’.

Yes its ugly brute force, but it works for now. 🙂

Fixing graphic sizes

This is our current hold-up. We get these sort of errors during the build process (interesting bits highlighted)

CopyPNGFile /Users/seamonkey/Library/Developer/Xcode/DerivedData/test_dragon-cpppmvfcbrjfzsaboqlzbunwvano/Build/Products/Debug-iphoneos/test_dragon.app/settings-button-down.png test_dragon/resources-ipadhd/settings-button-down.pngcd /Users/seamonkey/Documents/test_ccbuilder/test_dragonsetenv PATH "/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/usr/bin:/Applications/Xcode.app/Contents/Developer/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin"/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/usr/bin/copypng -compress "" /Users/seamonkey/Documents/test_ccbuilder/test_dragon/test_dragon/resources-ipadhd/settings-button-down.png /Users/seamonkey/Library/Developer/Xcode/DerivedData/test_dragon-cpppmvfcbrjfzsaboqlzbunwvano/Build/Products/Debug-iphoneos/test_dragon.app/settings-button-down.png
While reading /Users/seamonkey/Documents/test_ccbuilder/test_dragon/test_dragon/resources-ipadhd/settings-button-down.png pngcrush caught libpng error: Read ErCommand /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/usr/bin/copypng emitted errors but did not return a nonzero exit code to indicate failure

Some quick reading shows its an xcode thing rather than a cocos thing; xcode by default compresses images when they get bundled into the app. Other people have encountered this error, with 2 suggested causes/actions:

  • The image doesn’t exist, but xcode thinks it does. Seems to be more common, people have deleted images from their project, but xcode keeps trying to process it anyway. Doing a project clean and manually editing plist files etc seems to fix.
  • The image is corrupt. Re-saving in photoshop usually fixes.

Clearly we don’t need the first solution. We tried the second solution, that doesn’t work.

Interestingly, each build seems to affect a different image, which leads us to think it might be something else. We’ve noticed that cocosbuilder handles the different iOS image sizes by making a folder for each device type (iphone, iphone retina, ipad, ipad retina), and putting identically named images in each. We’ve found Xcode in the past gets confused by multiple files with the same name, even if they’re in different folders, could it be the same problem here? Still investigating.

*time passes*

Tried again with a clean xcode project, this time we don’t get the errors, but get multiple warnings like this:

Warning: Multiple build commands for output file

/Users/seamonkey/Library/Developer/Xcode/DerivedData/test_dragonaltfolders-bhissnkaolzjlobqrjxstmkiozny/Build/Products/Debug-iphonesimulator/test_dragonaltfolders.app/cloud.png

Which seems more in like with our thinking; xcode is getting confused by the multiple images with the same name. Are we not bringing the resources into xcode correctly perhaps? I’ve tried both as ‘copy everything’ and ‘links’ (aka yellow folders vs blue folders). Linked folders doesn’t find the images at all, copied folders finds the images, but they display incorrectly. Hmm.

Whats amusing/frustrating about this whole thing is that Cocosbuilder -> Cocosplayer does this entire process perfectly, in an instant, with no user intervention. Oh well.

Anyways, that’s where we’re up to, any advice appreciated! Hope this helps others too. 🙂

 Troubleshooting

These are half-remembered errors as we learned this process, but they might be useful if you get stuck:

main.js not found

(or any js files not found), can be

  • you’ve not ticked the files to be included in the target. select the js file in the navigator, look on the pane on the right side; under ‘target membership’ there should be a tick next to the name of your project. if not, that file won’t be exported. you can multi-select files and then enable the toggle, or better remember the next time you drag files into the resources, to tick the ‘add to target’ option.
  • the files are being compiled, not copied. check in the build phases, they should be under the copy section.
  • require lines are missing.  it should be in the auto-generated main.js, we tried manually editing main.js to start with, getting all the required names messed us up a few times

cbb files aren’t loading, errors on loadAsScene

make sure you’ve added the #include “CBBReader.h” line.

images not found

check you’ve copied folders (yellow folders), not created a folder reference (blue folders).

testing the html5 version of the games with chrome hangs at a black screen

yes it does *shrug*. try safari instead, works for us.

2 Comments

  1. 2SA Studio says:

    Nice tutorial!
    We’ve also been struggling to compile CocosBuilder + js with Xcode (and also with Eclipse, for the Android side), we finally came up with the following architecture: http://2sa-studio.blogspot.fr/2013/04/setup-cross-platform-project-with.html.

    Thanks for sharing your experience!

  2. lucy says:

    thanks, will check our your post and give it a try. 🙂

Leave a Reply