The Ultimate Cocos2D Project: Libraries

On March 4, 2011, in cocos2d, Kobold2D, by Steffen Itterheim

The Ultimate Cocos2D Project is: Kobold2D!

Put simply: Kobold2D is designed to make Cocos2D developers more productive.

Original Post

Last week I wrote that I’m Building The Ultimate Cocos2D Xcode Project. In today’s weekly update I wanted to give you some more details on the use of libraries in that project.

Cocos3D included

So there happens to be a Cocos3D now. Rather than being part of the Cocos2D distribution, it’s an extension project. Guess what that means? Right, installing Cocos3D means fumbling with the dreaded install-templates.sh script (see this Cocos3D tutorial). Of course the first user reactions were: how do I install it? Installation failed, what am I doing wrong? And so on …

The Ultimate Cocos2D Project wouldn’t be ultimate if it didn’t include Cocos3D out of the box. And unmodified of course, as with all included libraries I want to make it as simple as possible to replace one library version with another. Once you get to half a dozen of included libraries, maintaining them all can become a hassle, so the very least I can do is to make it easy for everyone to upgrade specific libraries.

Obviously: Cocos2D included

Of course Cocos2D is also included as a static library as opposed to cluttering your project with all of its source files. Xcode project references make it very convenient to add external code and keeping it seperate. I’ve described the process in detail in my Cocos2D Xcode Project tutorial but since then I’ve learned a couple more things about how to make this even better.

For example, I no longer include cocos2d-iphone directly, instead there’s a seperate Xcode project in between so that I have full control over build settings (using XCConfig files) and make it possible to build both iOS and Mac OS targets in the same Xcode project. I will also include the current version of Cocos2D in the download because my goal is to make everything work out of the box.

No fumbling with install scripts, no additional downloads necessary, no need to modify any Xcode build settings – including developer certificates and header search paths. Build configurations for Ad Hoc and App Store release builds are also included, which will create .IPA and .ZIP files for you ready for Ad Hoc distribution respectively upload on iTunes Connect.

Popular libraries included

Now let’s get to the juicy part. Early on I realized that Cocos2D users often needed (or wanted) to include other libraries. Some of them have become so popular among the Cocos2D crowd that they could as well be part of the official distribution. Alas, they’re not. That’s a service I want to provide.

Often those libraries require special and non-obvious steps to successfully add them to an existing project. All too often those steps are either undocumented, untested, hard to follow, refer to outdated versions of Xcode, iOS SDK, etc. and generally require technical expertise of project configuration and compiler settings.

This is all taken care of for you. Here’s the list of libraries that are already included in the Ultimate Cocos2D Xcode Project:

That is quite a list. All you need to do to use these libraries is to either enable them in code or merely include the header file and start using them. If you worry that all these libraries will bloat your App, rest assured that Xcode is very clever: if you don’t actually make use of a static library (eg don’t include any of its header files), it will not be linked with your App and not waste any space or performance. I verified that.

Update policy

These are a lot of libraries to keep up to date. I plan to make about 4-8 point releases each year, usually triggered by a major (speak: non-beta) release of Cocos2D. If updating other libraries justifies an update depends on the library’s importance and the significance of the update.

Your libraries

Adding your own libraries to the project will be easy and the process will be documented. This will encourage code-sharing because your library will just work with other user’s project, it only needs to follow a few simple guidelines to become plugin-capable. This opens the door for better and tighter integration of 3rd party code into your projects. Even if you don’t intend to share your code, you’ll still benefit because your code will be easier to re-use and maintain.

Also, if you like you can make a request for a specific library or additional source code that should be included in the project, please leave a comment. I’ll see what I can do. :)

Building The Ultimate Cocos2D Project

On February 25, 2011, in Kobold2D, by Steffen Itterheim

The Ultimate Cocos2D Project is: Kobold2D!

Put simply: Kobold2D is designed to make Cocos2D developers more productive.

Original Post

First Friday update after the teaser post. I’m working on a new project. I’m still fleshing out the details of the “killer-feature” and making tests, so I can’t really talk about that. But I can tell you what I have already up and running.

The Ancestor: cocos2d-project

You may remember the Xcode Cocos2D project tutorial I wrote almost a year ago. The goal of that was to use Cocos2D as an external library in order to be able to update Cocos2D simply by pulling a new version from git, or just by replacing the Cocos2D folder. I gave the resulting project a boring, uninteresting, generic name (so typical for a programmer): cocos2d-project.

The new and improved cocos2d-project not only has a spiffy name (to be announced) but also raises the bar not one but two or maybe even three levels, depending on perceived value. It’s definitely leaps and bounds ahead of the Cocos2D distribution project, especially if you care for how source code projects should be composed.

One Xcode project for both iOS & Mac OS X Targets

One thing that really bothered me when Cocos2D became capable to build Mac OS X applications was that it required a separate Xcode project for each platform. If you’ve ever done cross-platform development you know this isn’t going to make you happy. Every action needs to be done twice, add a resource in one project, then you must also add it in the other. Change a build setting in one project, also change it in the other. Build and run in one project, then build and run the other project with a completely different window layout and probably duplicating all the floating windows aka “Is that the Mac OS debugger or is it the one for the iOS project?”. You name it.

I did some research, then a test, and It turns out: it’s entirely possible to target both the Mac OS X and iOS platform from within the same Xcode project. It works like a charm!

Really the only thing you need to keep in mind is that Xcode doesn’t give you the option to change the Active SDK by default. But if you click the Overview dropdown while holding down the Option key, you can select any SDK that’s installed on your system (see the image). The key here is to first change the Active Target to the Mac target, then Option-Click again and select Mac OS X 10.6 as the Active SDK. And the other way around to change back to iOS. So it’s a two step process but still way more comfortable than managing two seperate Xcode projects.

XCConfig Build Configuration

Behind the scenes there’s an additional step required to make this work, which I’ve been wanting to do for a long time: to use XCConfig files for build settings. Cocoaphony has a blog post Abandoning the Build Panel describing the technique. The good part is: there’s less confusion between project-wide and target-specific build settings. Even more importantly, if you build several different libraries you want to build them with the exact same settings – with XCConfig files this is easy to do, manually changing the build settings of several projects with multiple targets simply isn’t practical.

Plus you can document each setting and you can still use the Build Settings Panel for your own needs while allowing me to use system-critical changes to the Build Settings. For example, if a certain build setting causes issues (eg like the switch to LLVM GCC) then I can change the setting and release a new version of the project, or just the build config file separately. You can then replace that file and it should fix the build (assuming you haven’t change that exact setting in the Build Panel). All of your customized Build Settings will remain untouched of course.

Those are only two very fundamental improvements on a system engineering level which probably won’t excite you too much if you focus on making games with any means necessary. I’m keeping the good stuff for a future update, hopefully in 3 to 4 weeks I’ll be able to give you some first details about the “killer-feature”. :)

I almost forgot about the Cocos2D-Project on github. While it works flawlessly with the latest v0.99.5 stable release of Cocos2D, it was still bundled with only the RC1 (release candidate). So I’ve updated the cocos2d version in the repository.

In case you don’t know what Cocos2D-Project is:

Cocos2D-Project is a great way to start any Cocos2D-iPhone based project.

It eases up- and downgrading the Cocos2D game engine at any time. It includes additional source code as well as multiple targets and build configurations for Ad Hoc & App Store distribution (creates the necessary IPA/ZIP files) and debugging of memory leaks and related issues.

Cocos2D-Project is free, open-source, uses the MIT License and comes already bundled with the cocos2d-iphone version that it currently works with “out of the box”.

It’s not affiliated with or endorsed by cocos2d-iphone.org and Ricardo Quesada. You will get support for Cocos2D-Project on Cocos2D Central.

Future updates

With the help of others, the Cocos2D-Project development has taken on a life of its own. The current work in progress is much more than a simple Xcode project referencing just the Cocos2D game engine. I’m looking forward to announce a big update in a couple weeks. Stay tuned.

Tagged with: