Unofficial Cocos2D API Reference

On January 25, 2011, in cocos2d, support, by Steffen Itterheim

I’m now hosting an unofficial Cocos2D (for iOS & Mac OS) API Reference, accessible via the Knowledge Base tab.

What’s so “unofficial” about it?

My version of the API reference includes previously undocumented classes, some are documented but just not in the official documentation, others are completely undocumented but at least now you know they’re there. Currently, there is no additional documentation added other than what’s in the official cocos2d source code files, and as far as I can tell nothing is missing. If there is, please let me know.

Since at least the release of v0.99.5 about a month ago important classes like CCLayer, CCArray and CCDirectorIOS have been missing from the official API reference. Did anyone even take notice, or was it just me? I hope it will be fixed soon and the missing classes added back to the official API reference.

I’d like to call it “unofficial” just to make sure everyone gets the idea that I’m not involved in the development of Cocos2D in any way, and my version of the API reference may contain crucial omissions or mistakes as well.

Angry Birds Tutorial causes slowdown

Current and well-deserved cause of the cocos2d-iphone.org slowdown is the SpaceManager Game Tutorial with source code by the mobile bros. LLC. The tutorial shows you how to make an Angry Birds style of game.

Back from the devs

On October 5, 2010, in Announcements, by Steffen Itterheim

I’m back from Macoun, and it was nice meeting you all! Well, actually since that conference was just a 90 minute ride away, so I wasn’t really gone, except mentally. I spent a lot of time last week to prepare my presentation (in german), and fighting a cold. The subject was a game component system that I wrote on top of cocos2d, to encapsulate most of the cocos2d CCNode stuff and allowing me to focus on writing re-usable gameplay components. The system works but it’s not production tested. Still it’s proven very promising from my initial tests and opens some interesting opportunities, for example the re-use of components is a huge timesaver, and you can totally get rid of any class hierarchy and remain flexible throughout development. Due to writing the book and other things I hadn’t had the time to develop it as much as I wanted to. I’ll release it eventually but for the moment, I have a different focus.

For one, I’m late with the Game Center chapter due to the Macoun conference preparations, an upcoming wedding and an apartment renovation of the soon-to-be-wed as their wedding gift. So I’ll try to cram writing both the Game Center chapter and the final chapter in this week, before turning my attention to updating the Line-Drawing Starterkit and Xcode project. I did not intend to support non-beta versions of cocos2d, but given how long the recent betas last and how many developers actually use the latest beta (probably due to HD support) and how significant the breaking changes are this time, I’m going to update the starterkit and Xcode project with HD support while keeping the old project for those who would rather use the stable 0.99.4 version of cocos2d. Once that’s done, it’ll be mid of October and another project, only partly concerning cocos2d, kicks in full speed. No time to lose.

Speaking of the Starterkit, September went by and I made 10 sales, without advertising it or anything, so those numbers are at the lower end of the “potential sales” spectrum. That’s a sum (over $1,500) that I can live with. Well, actually, that’s a sum that I can live off of. On a related matter, I recently found a page detailling the traffic stats of the cocos2d-iphone.org website. If those stats are correct, the unique visits are over ten times that of my site. Now, frankly speaking, every time I get those little facts and stats from here and there over the past couple months, and then added up the numbers, compared them with mine, applied reasonably pessimistic estimations and caution, I do wonder: why the hell isn’t cocos2d run like a business?

If you ask me, with those traffic stats and a reasonable conversion rate of 0.1% per unique visitor (mine is over 0.2%), one could easily pay 3 people to develop cocos2d, test it, write documentation, moderate the forum, and in general adding more business value. Which in turn grows the business, speeds up the development of the engine, tools and by-products and will make everyone benefit from that. I don’t get it. Because at this point, it’s either going to be that, or a slow decline to a niche product over the next couple years due to the increasingly strong competition from other iOS engines. Especially those that offer cross-platform support, since that’s what contractors are asking for, or even demanding, more and more.

Anyhow, for my part, I decided that now would be a good time to start doing the Indie thing full-time, still accepting contract work but I’m able to be a lot pickier about it. I have a goal set out for myself, and it’s not a simple one. I’ve always enjoyed most to help my colleagues, to fix their problems, to support them and in general, to help them achieve excellence. I know, that sounds like something you’d find in EA’s job matrix – and in fact, you do. Helping others achieve excellence, throughout my professional career, that’s what I’ve been doing and enjoying the most. Now I find myself doing that for cocos2d developers, enjoying it and being able to support myself in the process. Well, I think I’ll have to thank you, my dear readers, for that. :)

As a thank you back, I’ve started working on a bigger project about 3 months ago that will be useful and helpful to many indie game developers, regardless of the engine you may be using. Hence it deserves its own website and a cool name (darn, that is hard!). I’m looking forward to really getting into high gear with it after I’ve submitted the remaining book chapters. Stay tuned.

I’m pleased to announce that the Line-Drawing Game Starterkit is finally available for sale! It’s a source code project for anyone interested in developing a line-drawing game. The gameplay is modelled after the famous Flight Control game. The Starterkit works with the latest cocos2d v0.99.4 version and will at the very least receive compatibility upgrades for future cocos2d versions.

Hop on over to the product page to check out the feature list, the API documentation and a source code sample. You can also download the Starterkit App for iPhone from iTunes. The iPad Edition is still in approval.

Note: for the reminder of July 2010 you can get the Starterkit at an introductory price for only $179!

Positioning of the Starterkit

I’m sorry that you’ve had to wait one and a half months compared to the initially planned release date of June 1st. I double and triple checked every decision I made and you can see some of the results on the Starterkit product page.

I’ve also decided to increase the regular price from the initially intended $199 to $299 effective from August 1st, 2010. One of the reasons being that I initially planned to have multiple licenses including Indie and Commercial ones. I thought long and hard about positioning the Starterkit and eventually decided to sell only Site Licenses. For the individual developer it costs a bit more but for small and commercial teams it’s great news, and small teams and established, dedicated developers is who I am targeting. Those who really appreciate the value of commercial source code saving days and weeks of research and development, and all the trouble, sweat and pain associated with it. And I’m here to help if you have any questions regarding the Starterkit’s source code.

I don’t have plans to make another Starterkit and in all likelihood it will remain the only commercial cocos2d-related product for the remainder of this year.

Book Chapter about Line-Drawing Games

For those who are disappointed about the new price, either grab the Starterkit before August 1st or wait until December for the Learn iPhone and iPad Cocos2D Game Development book I’m writing. It will contain a chapter covering some of the basic aspects of a line-drawing game but without the finer details and complex interactions conveyed in the Starterkit. It’ll be Chapter 12 so in about 8 weeks (Mid-September) I’ll mention it in my weekly book chapter posts.

Closed Sales Period, Summary of

And here’s for transparency: exactly 10 days ago I informed the 668 subscribers of my Newsletter of the closed sales period. The password-protected Starterkit product page received just over 200 unique visitors. During the last 10 days I made 9 sales amounting to about $1,530 with Plimus’ 5% fee already deducted but obviously before tax. All sales were made within the first 4 days after I sent the Newsletter and for the last 6 days sales were absolutely zero. Although I’ve been in contact with several interested parties who didn’t want to or simply couldn’t buy it right now for various reasons. If you’re one of them: you’ll get it for $179 no matter when you make the purchase, just contact me beforehand.

Right now I’m curious to see how sales will be now that the Starterkit is publicly available.

Starterkit Promotion

I’d appreciate if you would tweet and re-tweet this post and mention the Starterkit to all fellow cocos2d-sians! If you would even go so far as writing a serious and honest review on your blog, please get in touch with me.

Just don’t test the waters by mentioning the Starterkit in the cocos2d community forum.

Stance Lance

I wish Ricardo had taken the time to be considerate and then talked to me instead of running off making an assumptive, excessive, and for the most part irrelevant (off-topic) stance post which only served to cause a big commotion among his community while allowing his forum rule “Treat people with respect.” to become a farce.

In Conclusion

In hindsight I’m glad that the whole thing got me thinking in so many new directions. Most importantly it got me in contact with a lot of developers who consciously don’t post on the cocos2d forum. To get those encouraging words and positive feedback and gaining interesting insights from other developer’s perspectives – especially those who tag along silently – really helped me understand the cocos2d development community better. Thank you, you know who you are!

The whole shebang also served as a great motivational factor to pour my everything into the cocos2d book, which came at just the right time to let off steam in just the right way. I’m writing it to be the cocos2d documentation it deserves and the one I always wished it had. I can’t even begin to describe how satisfying it feels to write this book. So much in fact that it hurts to stop writing every time I reach the 27 pages each chapter is expected to have. :)

cocos2d Book, Chapter 4: First Simple Game

On July 17, 2010, in Announcements, book, cocos2d, by Steffen Itterheim

Chapter 4 – First Simple Game

After Chapter 3 covered the fundamentals of the cocos2d game engine, this chapter will put to use what you’ve learned. The simple game is all about droping enemies that you have to avoid via accelerometer controls. Sort of like an inverse Doodle Jump. But it’s not just about the gameplay itself, I want the game to be reasonably complete with a main menu, scene transitions, game over and of course audio.

The chapter will be submitted on Friday, July 23rd.

Do you have any suggestions for the game?

What do you think should be in a first cocos2d game? Let me know!

Summary of working on Chapter 3 – Essentials

When I started the chapter I wasn’t really sure about its focus and progress was a little slow. Eventually it clicked and I found myself ending up having written more pages than needed and still having a great number of things left untold. The key was looking at the cocos2d API reference documentation and remembering what it was like when I was a beginner. Sure, every class, method and property is there but for a beginning cocos2d developer the API reference is just a huge list of names. In other words, if your experience was or is anything like mine was, it’s frustrating to work with the API reference.

I ended up writing about the cocos2d engine design and its scene graph first, the remaining 80% of the chapter explain in detail with lots of code samples how to use those darn CCNode classes. All the important ones are covered: CCNode, CCScene, CCLayer, CCSprite, CCLabel, CCMenu, CCMenuItem* as well as the Director, Transitions and Actions. Besides the code samples and how-to I’ve added numerous caveats, common mistakes, best practices and other nodes which are so very much needed to make any documentation complete.

For example, how Layers are best used for grouping other nodes together and of course how to enable touch and accelerometer input by adding the required functions which aren’t mentioned in the API reference since they are part of the iPhone SDK API. There’s also some weird recommendation floating around not to use too many Layers because they’re slow. I can’t find the source but what I did find was that this is only true if the Layers enable touch or accelerometer input, because that’s what costs a lot of performance. So what you don’t want to have is several layers accepting input, otherwise use as many Layers as you need – which shouldn’t be many anyway. And if you do need multiple Layers accepting input, why not just use one master Layer (possibly using a Targeted Touch handler) which forwards the input events appropriately to the other Layers?

cocos2d Book, Chapter 3: Essentials

On July 10, 2010, in Announcements, book, cocos2d, by Steffen Itterheim

Chapter 3 – Essentials

This chapter is a reference about the fundamental classes of cocos2d and how to use them. Nodes, Layers, Scenes, Labels, Sprites, Transitions, Actions, you name it. Also CCDirector, SimpleAudioEngine and other often used singleton classes as well. More advanced concepts will be discussed in a later chapter, Spritesheets for example.

The submission of the first chapter draft is due next Friday, July 16th.

What do you think should be in Chapter 3?

Do you know a cocos2d class or process that you think is essential and should be discussed in this chapter? Let me know!

Summary of working on Chapter 2 – Getting Started

For one I detailed the Hello World sample project and made a simple modification using touch input. At the same time at least some basic level of understanding about cocos2d classes was introduced but the gist of it is done in Chapter 3. In addition, there were a lot of theoretical aspects I wanted to discuss as well, most of all Memory Management and available memory as well as setting expectations on testing on Simulator vs. a device. And of course the devices and their subtle differences. I do hope that those kind of details are appreciated even if they’re not 100% related to cocos2d. I regularly see cocos2d developers struggling with memory issues, with unexpected differences on the device vs the Simulator, or comparing framerates of the Simulator and possibly even Debug builds. That made me want to stray off the beaten path for a moment to hopefully save the readers some misconceptions and the pain associated with them.

I also realized how many steps a new developer has to go through and how much there is to learn in case you’ve never been working with the iPhone SDK before. It starts with registering as iPhone developer and doesn’t end with installing the SDK because you also need the provisioning profiles, a much discussed and troublesome feature. For all of this I refered to existing (and excellent) Apple documentation. Typically the processes change with each new iPhone SDK or may even be under NDA, so discussing how all of this works with iPhone SDK 4 wouldn’t be a good idea since shortly after the book is out iPhone SDK 5 may be coming, introducing changes to the Developer Portal and iTunes Connect with it. It did get me the idea, and I know others have it too, that we need some holding-hands Tutorial which takes one through the steps from registering as iPhone Developer to publishing one’s first App, by referring to the correct official documentation for each step while not forgetting about common pitfalls that are not in the official docs.

I also noticed how easy it can be to overlook how you suddenly introduce a new concept without explaining it first. And then you have to decide how much information is necessary to introduce the concept without straying too far away from what you want to talk about in the first place. It’s especially hard for me because I tend to want to explain everything in detail but some things have to be left for a later discussion. I’m looking forward to editorial feedback now. It has helped tremendeously for the first chapter and I learned a lot from the Apress editorial staff, so I find it exciting that the experts point me to the flaws and make suggestions, I go in to fix them and then see how much better it is. That’s how I like to learn things and it’s going to be one of the core concepts of the book. Show how it’s done, how it shouldn’t be done (if it’s often done wrong) and how it can be done even better if you want to avoid trouble in the long run, while explaining why.

Prefer Composition over Inheritance

On June 11, 2010, in Programming, Speaking From Experience, by Steffen Itterheim

When the question came up whether to subclass CCSprite or use some model class to build your game entity hierarchy in the cocos2d forum, i stressed that one should try not to use inheritance and keep the inheritance hierarchy to as few levels as possible. I’ve worked with codebases with hundreds of thousands of lines of code, and hundreds of different types of actors in the world. Yet the inheritance hierarchy was 2 super (parent) classes for almost all objects, only very few game objects had 3 or 4 super classes. How can you make complex games this way?

The answer lies in composition, often referred to as Game Components by engines like TorqueX and the PushButton Engine (a Flash game engine from the original Torque developers). This video from the PushButton lead developer Ben Garney explains it very well and also illustrates the problem with inheritance over-use in game engines. Something that most developers new to object-oriented and/or game programming do in fact tend to over-use – i blame that on poorly written books and other introductory OOP sources which emphasize inheritance without discussing its disadvantages.

You can read more about PushButton’s Components system in their documentation. How they implemented Components in TorqueX and what the differences are to XNA Game Components further enhances understanding of the concept.

For further reading and arguments read the Wikipedia article on component based software engineering. As a matter of fact, the Objective-C language was invented to be able to create re-usable software components!

Scott Bilas’ GDC 2002 talk about A Data-Driven Game Object System (PDF) as used by Dungeon Siege contains more pointers on why inheritance fails for game developers and what the advantages (but also some caveats) are with component-based game engines. The talk may be old but it’s still as valid today as it was back then. In fact, in 2002 i started working on SpellForce which already had a component system built into its core, called Aspects, Abilities and Spells. It allowed us to enter all the game data in the database and programmers only needed to write the generic code that dealt with the data, as well as setting certain limits and validity checks (eg. you couldn’t use a damaging spell on yourself but if you wanted to you could target enemies with your heal spell, or have archers shoot buildings … errm).

During GDC 2009 a similar presentation was held by Radical Entertainment’s Marcin Chady. The talk was called Theory and Practice of Game Object Component Architecture (PPT).

Mick West wrote an article Refactoring Game Entities with Components which describes the challenges and benefits of changing the Tony Hawk codebase from an inheritance model to a game component system.

A somewhat more advanced read on component use is a collaborative paper called Dynamic Game Object Component System for Mutable Behavior Characters which talks about components in context of finite state machines and NPC behaviors with a rule-based activation system.

The Game Architect blog calls it an Anatomy of Despair and sums up very good what the cons of inheritance-based class design is and how composition solves them.

Starterkit: Line-Drawing

On May 27, 2010, in , by Steffen Itterheim

Line-Drawing Game Starterkit

Site License! Unlimited Apps!

Royalty Free! No Attribution!

60 day money-back guarantee!

Made with the popular cocos2d-iphone game engine.
Compatible with cocos2d-iphone v1.1 and v2.0, Xcode 4.6 and iOS 6.
Includes ARC enabled versions of the starterkit!


Sale – only $49 !


All Starterkit project artwork provided by Arezou Ipakchi Design. Promotional images created by Justin from CartoonSmart.

What it is:

Get a head-start for your Line-Drawing game and save days if not weeks of your time! You’ll get gameplay code modelled after the extremely popular Flight Control game. You’ll learn how to draw lines, detect touches on objects, have objects follow a path – and much, much more! Written by a professional game developer and game industry veteran (me) the source code is annotated with lots of comments explaining my rationale and written with readability in mind.

Contains separate iPhone & iPad targets!

The Starterkit includes targets for iPhone and iPad using the same code if you don’t want to create a Universal app, for example to reduce your app’s size or to be able to charge more for the iPad version. If the iPad Target is selected hi-res iPad images will be used. Image selection is done automatically by loading those images whose filenames have the “-ipad” suffix, the same suffix cocos2d uses.

What others are saying:

“Code is quite clearly written and decently documented […] definitely a fine investment.”
From: Commercial cocos2d Code review from Alex Curylo.

“It was an awesome moment when I found the source for a line draw game of this caliber.”
-Franklin Lyons, SpinFall

“Especially the path and movement system is saving me lots of headaches.”
-Martin Hoffmann

Games made with this Starterkit:

Launch Control

Ferries HD

Feature List:

  • cleanly seperated and well-structured GameScene code design with a minimum of dependencies
  • easy to add new objects and extend object parameters
  • touch object & draw a path for it (whether it’s already following a path or not)
  • path drawing ends when path is drawn over appropriate target location (eg airstrip for airplanes, respecting angle of approach)
  • path drawing ends when arbitrary point limit is exceeded (to avoid slowdowns)
  • path is drawn when dragged with thick transparent line style like Harbor Master, without glitches
  • path is split into equal length pieces no matter how quickly user moves finger
  • objects spawn outside screen, locations can be re-defined and extended
  • objects display incoming warning marker at screen border
  • objects display collision warning when any two of them are getting too close
  • objects follow path to end – then fade out and increase score or continue moving
  • objects always rotate in movement direction
  • objects bounce back at screen borders
  • motivational Labels for successful landings, precached
  • Score and HighScore Labels
  • HighScore saved to disk between play sessions
  • supports both Landscape orientations with autorotation
  • loads correct resource files depending on Target (iPhone or iPad)
  • proper Pause handling for incoming calls, SMS
  • many generally useful Math Helper functions included
  • lots of comments explaining rationale and giving tips for improvement
  • assertive coding style to help catch coding errors early on
  • offline and online documentation
  • you can choose between using cocos2d-iphone v1.1 and v2.0
  • you can choose between using ARC or classic manual reference counting
  • compatible with iOS 5.0 and newer, including iOS 6
  • compatible with Xcode 4.6 (the most recent versions also work)
  • easy setup: just unzip, open Xcode project, select build scheme, build and run

Questions? Need Help?

Just send me an email.

Legal Disclaimer

Cocos2D is a registered trademark of Ricardo Quesada. Steffen Itterheim, the Learn & Master Cocos2D website and the Line-Drawing Game Starterkit are neither affiliated with nor endorsed by Zynga or Ricardo Quesada.


Try Before Buy!

Demo App for iPhone
Demo App for iPad

Browse the API Documentation

View a Code Sample


Buy Now!

Site License! Unlimited Apps!

Royalty Free! No Attribution!

60 day money-back guarantee!

Made with the popular cocos2d-iphone game engine.
Compatible with cocos2d-iphone v1.1 and v2.0, Xcode 4.6 and iOS 6.
Includes ARC enabled versions of the starterkit!


Sale – only $49 !



License Agreement

Copyright

Purchase grants you the License to use and modify the source code and assets under the following Terms and Conditions:

You are not allowed to make the source code publicly available. You are not allowed to give or sell the source code to others, modified or not. Licenses are not transferable.

All Licenses are royalty free. You can make as many free or commercial Apps using the source code as you want. You may re-use any existing assets in your App.

If you do contract work and have or want to give the Starterkit source code to your client, your client needs to purchase a Site License as well.

Site License

Each purchase grants you a Site License. The Site license grants you the use of the Starterkit without restrictions at one site.

A site is an office, building or living space rented or owned by the company or individual making the purchase. It allows anyone working on site to use and modify the Starterkit source code.

Large companies operating at several sites need to purchase a site license for each individual location if the Starterkit is to be used at multiple locations. Contact me if you’re such a corporation and you prefer a flat fee license with your own license text to go along with it.

Support

Updates to the Starterkit are done on an as needed basis. I will also keep it up to date and running with the latest stable releases of cocos2d. Updates are distributed via a download link sent to the email address you used for your order. If your email address ever changes please contact me, ideally you should forward me your order confirmation in that case to speed up the change.

Source Code not covered by this License

The licensed Source Code project contains files which are available for free and are governed by different licenses. The Terms & Conditions outlined here do not apply to source code files which do not contain the Copyright notice “Copyright (year) Steffen Itterheim. All rights reserved.”.

Disclaimer

THIS SOFTWARE IS PROVIDED “AS IS” AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Questions? Contact me!

If you have any questions or if you require specific License texts before making a purchase, please contact me.



On May 27th, the whole world saw the future. Because i told you so!


Line-Drawing Game Starterkit –> June 1st!


What’s that you ask?

It is the ideal starting point for your own Line-Drawing game! (like Flight Control and Harbor Master) It is a cocos2d source code project that will be available for sale. But not sight unseen, no. It will appear on the App Store for you to try out. And you get more, the full doxygen-generated source code documentation is available for browsing right now! Just so that you can assess the scope of the project.

What will it cost?

I admit i haven’t decided on that yet.

Show me your license!

Alright, alright. I’ll be fair: Free lifetime upgrades! Unlimited number of developers!

Each license is good for one published game. Additional licenses for follow-up games come at a discount. “Lite” versions do not require an extra license since they are essentially the same game. There will also be a commercial license for developers or studios who make more than $6,000 per month in revenue and can easily afford a higher price.

Why, please tell me why?

Because i can. I like technology and i like programming games. I’m also an enabler and i would love to see others build something unique based on game development technology i provide.

Anything else?

Yes. Today sees the premature end of the best new show of last year. RIP Flash Forward.

Page 3 of 41234