The Ultimate Cocos2D Project: Kobold2D

On March 19, 2011, in Kobold2D, by Steffen Itterheim

What is Kobold2D?

It’s the Ultimate Cocos2D Project, of course. Or more precisely, the official name for it. Right now, the website is only a “coming soon” page while development is under way.

What’s in a name?

Calling it “The Ultimate Cocos2D Project” all the time would have become tedious rather quickly. I wanted a name that is reminiscent of Cocos2D yet completely different. As luck would have it, I’ve recently watched a lot of Battlestar Galactica episodes. You might remember that in this show humanity’s home planet is called Kobol. I couldn’t help but think of COBOL all the time. 😉

From there it was a small step to Kobold, which in germany is widely associated with a famous cartoon Kobold called Pumuckl. As a kid, I was a big fan of Pumuckl, so picking Kobold2D as the name was a no brainer. Even more so since it has the same ring to it than Cocos2D.

Why create a new brand name?

For one, giving the project a name of its own clearly makes it more attractive. It expresses a certain dedication to the project. It should also signal that it’s no longer just about Cocos2D. With all those extra libraries and additional glue code, plus an experimental project I’m working on, I’m tempted to call it a Game Development Kit (GDK). That’s the long term vision for Kobold2D: more power, easier – for everyone!

Speaking of long term, that’s another reason to give it its own brand name. The visionary thought being that ultimately, something like Kobold2D could be implemented for other game engines as well, with the same core values: give the developers more power, greater flexibility but at the same time make it easier for them to get started.

The Kobold Team

I’m not the only developer who is aching for a more professional work environment. Kobold2D is a joint-venture with another senior software developer and a couple helping hands who help out wherever and whenever they can. We agreed to share the development burden on a voluntary basis. We all have different stakes and interests in the development of Kobold2D.

For me personally the most important aspect is my ambition to develop a project for its users, both professional and casual. I know I can build professional systems that are easy to use, well documented and thus get the job done painlessly. This basically sums up what I’ve been doing for the past 10 years.

What we’re not doing …

There’s one issue I think i going to come up, which might confuse some people, so I want to be clear about this: we are not creating a branch of Cocos2D. We have no intention to do so. We use the library as is, and we stick to the stable builds. The same goes for all other libraries of course.

At the same time, we don’t push each and every line of our additional code back or even contribute to the development of the libraries in Kobold2D. That’s not what we set out to do, and we simply don’t want to spend too much time consulting with and compromising on changes with others when our code is already there and working for us. Our code uses the MIT License, so it’s there for the taking.

In very few cases we can’t get around to modify library code. We only do this where necessary, for example if it breaks our build and the fix is rather simple. Other than that, if a library doesn’t work to our satisfaction, we try to add our fixes and improvements on top, either by subclassing or by making use of Objective-C categories. So far this has been working very well and allows us to keep updating the underlying libraries with far fewer hassles.

Next steps

One big task that I set myself out to complete before continuing with Kobold2D is figuring out the Xcode 4 template format for File Templates and Project Templates. I almost have everything together after spending practically the whole week on it. I’m also documenting all my findings and I’m going to publish the Xcode 4 Template Tutorial / Reference / Documentation / Manual (not sure about the name yet) by the end of the month.

The goal for Kobold2D is to have various project templates, which is why I’m doing extensive research on the new Xcode 4 template format. Unfortunately at the moment it seems that it will not work satisfactory with cross-referenced Xcode projects, but I remain positive that I can find a solution.

Kobold2D private beta!

There will also be a private beta test for Kobold2D starting in a couple weeks (couple == definitely more than 2 weeks). Reply to the private beta sign-up thread if you want a chance to be picked for the private beta test.

Tagged with:  

The Ultimate Cocos2D Project: Startup

On March 12, 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

Time for a weekly update. This time about startup code and configuration. One of the things that I frequently encountered following the development of Cocos2D and working with it, is how any change to the startup code – the main function, the App delegate and the root ViewController – caused issues and headscratching among developers.

I decided it doesn’t need to be this way.

The main() function

A code snippets speaks more than words:

[cc lang=”ObjC”]
int main(int argc, char *argv[])
return KKMain(argc, argv, NULL);

That’s right, all of the startup code is now part of the project’s source code. You can still do whatever you need to do before and after the call to KKMain (probably nothing, except maybe anti-piracy code). And the third parameter (NULL) to KKMain is reserved for future use, to pass in any configuration parameters if the need arises.

Let’s see what KKMain does:

[cc lang=”ObjC” height=”650″]
int KKMain(int argc, char* argv[], SMainParameters* userParameters)
SMainParameters parameters;
initMainParameters(&parameters, userParameters);

NSAutoreleasePool* pool = [[NSAutoreleasePool alloc] init];
// Mac OS X specific startup code
[MacGLView load_];

// This makes the CCDirector class known to wax:
[CCDirector class];
// wax setup is sufficient for all intents and purposes

[KKLua doString:kLuaInitScript];
[KKLua doString:kLuaInitScriptPlatformSpecific];
[KKLua doString:kLuaInitScriptForWax];

// This loads the config.lua file
[KKConfig loadConfigLua];

// run the app with the provided general-purpose AppDelegate which handles a lot of tedious stuff for you
int retVal = UIApplicationMain(argc, argv, nil, parameters.appDelegateClassName);
[pool release];
int retVal = NSApplicationMain(argc, (const char**)argv);

return retVal;

The usual, really, except that it also initializes Wax and thus Lua for your App as well as providing the necessary startup code for both supported platforms: iOS and Mac OS X. The KKLua class is an Objective-C wrapper around the most imortant Lua functions, most notably it has the doString and doFile methods which allow you to run any Lua code or file containing Lua code.

KKConfig is a class that loads a Lua table and stores it in a NSDictionary for fast access to Lua parameters at runtime. I’ll discuss it in detail another time. The main purpose of KKConfig is to loadConfigLua, which loads the config.lua script returning a table containing startup parameters and making those parameters available to Objective-C.

Config.lua in detail

Let’s have a quick look at an excerpt of the config.lua file. It contains all of the startup parameters a developer using Cocos2D would ever want to tweak in a conveniently editable Lua script:

[cc lang=”Lua” height=”400″]
local config =
KKStartupConfig =
— load first scene from a class with this name, or from a Lua script with this name with .lua appended
FirstSceneClassName = “GameScene”,

— set the director type, and the fallback in case the first isn’t available
DirectorType = DirectorType.DisplayLink,
DirectorTypeFallback = DirectorType.NSTimer,

MaxFrameRate = 60,
DisplayFPS = YES,
DisplayFPSInAdHocBuilds = NO,

— Render settings
DefaultTexturePixelFormat = TexturePixelFormat.RGB565,
GLViewColorFormat = GLViewColorFormat.RGB565,
GLViewDepthFormat = GLViewDepthFormat.DepthNone,
GLViewPreserveBackBuffer = NO,
GLViewMultiSampling = NO,
GLViewNumberOfSamples = 0,

Enable2DProjection = NO,
EnableRetinaDisplaySupport = YES,

— … and many more settings!

return config

Since you don’t want to guess what those settings mean, I’ve documented them for you:

Config.lua Parameter Documentation (PDF)

This should also illustrate the kind of documentation I’m striving for. Documentation will be available online. It’s created in a Confluence Wiki with the help of ScreenSteps for more visual, step-by-step documentation.

App Delegate & Root ViewController

You may be wondering how you can modify and tweak the App Delegate and Root ViewController if they’re both part of the distribution, rather than copied into each project? That’s actually very simple: both are regular Objective-C classes, so they can be subclassed and methods overridden as needed.

Both KKAppDelegate and KKRootViewController provide a default implementation which you can tweak with the config.lua parameters. If that shouldn’t be enough, for example if you have to plug in some 3rd party code into the App Delegate, each project will have a subclass of KKAppDelegate and KKRootViewController in which you can override any of the UIApplicationDelegate and UIViewController protocol methods. Usually you would first call the super implementation, unless you want to entirely replace the default behavior.

The KKAppDelegate method calls one specific method called initializationComplete at the end of the delegate method applicationDidFinishLaunching. This allows you to run any custom code right before the first scene is shown. You can use that to call the CCDirector runWithScene method manually, in case you have more than one scene which might be run as first scene depending on certain conditions.

If you set the FirstSceneClassName config.lua setting, the project will first check if there’s a classname.lua file. If so, it will run this Lua script, assuming it contains the implementation of the first scene (more on that some other time). Otherwise it checks if there’s an existing Objective-C class derived from CCScene with that name, and if so allocates and initializes this scene and calls runWithScene for you.

In essence

From your point of view, the execution of the App now starts with the first scene, before that there’s no code that you’ll have to concern yourself with. Any startup configuration tweaks that you need to do can be done comfortably via the config.lua file, and the only setting you’ll need to change is the name of the first scene’s class name or Lua script. In addition you’ll get access to some features out of the box, for example adding iAd banners is now a simple on/off switch.

Moreover, any time there’s a change in Cocos2D’s startup code, or the startup code in any other library (most notably Wax), I can just make those changes for you and release a new version. This isn’t something you need to concern yourself with anymore, and makes upgrading existing projects to new versions of Cocos2D and other libraries even easier.

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 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”. :)

A Teaser

On February 22, 2011, in Announcements, by Steffen Itterheim

I’m sorry for having been so absent lately. It just so happened that a couple events lead to taking some time off away from my computer, and then I realized how much I actually enjoyed not being at my computer all day long. Respectively how little motivation I had to go back to what I was used to doing because something was off, didn’t feel quite right. So I took some time off away from almost everything computer-ish, and started recreating and pondering.

Eventually I realized I was missing something:

  • a bigger-than-life goal
  • an actual, meaningful, worthwhile project that serves this goal

Once I had this realization, finding the right goal was easy:

The Goal

I want to create something new that will have a lasting impact on how we make games.

Nothing less. I could be more specific but I’m not willing to give that away yet.

The Project

I know exactly what I’m going to have to do but you’ll have to bear with me on the details – I’m just starting. Everything seems to have fallen in place and became so obvious. In fact, I’ve done it many times over in my professional career. What I’m now working on will enable you to make games faster and with fewer technical issues. It will trade performance and complexity for rapid development and ease of use.

I can’t stand it anymore

Quite frankly, I die a little every day I see nothing done to improve the miserable state new and inexperienced game developers face when they are starting out with Cocos2D. I am furious when I see that something as essential as the API reference isn’t even complete, and either no one but me notices or no one cares to mention it. Cocos2D is neglected in areas that I consider to be more important than the source code itself.

Cocos2D will soon support OpenGL ES 2.0 and shaders. That’s fine for some people and great news for a select few who actually know how to leverage the GL ES 2.0 features. However, I know in my heart this will only cause more headaches and frustration for the majority of users because for them more options only means they’re going to face more issues they don’t understand fully, which they can’t solve by themselves. Yet they’ll be tinkering with it because new technical toys are just too damn cool. But in the end it will only keep them from finishing their games. I’m much more concerned with fixing the recurring issues the majority of users are having. And helping them getting their games finished and out there.

I can’t change how Cocos2D is developed and how decisions are made. So I’m starting my own project to change the landscape, to raise the bar and set expectations to a level that satisfies the professional software engineer in me. I’ll stop trying to crack tough coconuts for you, instead I’ll lead you to new and greener pastures where the fruits are hanging low and have much softer shells. Poetically speaking. :)

My project will not be for everyone, but even for the seasoned developers there’s going to be something worthwhile in it. And you won’t have to give up on Cocos2D completely because even I will only slowly transition away from it.

When? What? Where? Etc.

The specifics of this project will be announced in due time. Just like I did with the book I’ll write a weekly, Friday-ish update post about recent developments and revealing new features. Also I will share with you my insights and thought processes and my approach to software development and what I’ve learned.

These posts serve an important purpose: by making public announcements, by writing down my goals and committing to them publicly, and by recording achievements my motivation will remain high, and I will keep enjoying what I’m doing. It also allows me to kick myself in the butt if I have to because I can’t possibly let you down. This will keep me going and will have me striving for nothing but excellence.

In the coming weeks and at least during the initial development phase I will focus almost all of my time on either project development, or recreation away from my computer. I will also try my best to avoid any and all distractions like forums, Twitter, email, unnecessary research, funny videos and generally just wasting time. If the past few weeks were any indication I will be harder to reach and even slower to communicate with. I will not be able to respond to every personal message because I need to focus my attention on the task at hand, or living my life as a crucial counter-weight. I will focus my attention more on speaking to the overall community via my Blog, Twitter and the planned Cocos2D Podcast with Mohammad Azam.

Watch this space for more info, and definitely join my Newsletter and follow me on Twitter.

I would like to preemptively thank you for your outstanding display of collaborative patience!

I’m off to building a better future! :)