While helping others solve their cocos2d project issues over the past year it became obvious that many projects have at least one major problem in one of these areas:
- memory management
- resource management
- code structure
Examples
Memory management issues normally range from allocating too much memory, either by loading too many textures up front which are only going to be needed later, or by memory leaks such as scenes not deallocating when switching scenes. Resource management problems range from not adding the right resources to the right target, often resulting in increased App size because resources are added to the bundle but never used by the App. It could also mean loading identical resource files except that they have different filenames (copies?), using up additional memory. Or not tightly packing sprites into Texture Atlases but instead using one Texture Atlas per game object - while this is understandable from a standpoint of logical seperation it does waste opportunities for optimization.
Finally, code structure or lack thereof regularly leads to “everything in one class” code design which is most likely an evolutionary process rather than intentional. It’s not uncommon to see classes with thousands of lines of code, sometimes even going past 10,000 lines of code in one class. Other things are using too many CCLayers without them adding a clear benefit, for example just to group all nodes at a specific z order together or to group them by functionality, eg one layer for enemies, one for players, one for background, one for UI, one for score, one for particle effects, and so on - without any of these layers being used for what they’re really good at: modifying multiple nodes at once, like moving, scaling, rotating or z-reordering them. And of course there’s the copy & paste hell, large blocks of code reproduced in various places only to modify some parameters instead of creating a method which takes the modifiable parameters as arguments. Even professionals I worked with got so used to doing that it became hard just to overcome the resistance of letting go of old habits. But they learned.
Summary
Nothing of this code design and structuring strikes me as odd or surprising. I’ve written code like this myself. I also believe if it’s good enough and works, then why the hell not? It’s a matter of experience and it’s only with experience that you clearly see how to improve things. This boils down to the regular learning curve where only training and tutoring and just simply making mistakes and learning from them helps in the long run. That’s how we learn things.
On the other hand, the things like Memory and Resource Management can also be learned but they have a different nature. They can be statistically assessed, they could be calculated and verified automatically. This makes me wonder if there isn’t some kind of automation and information tools that would help developers achieve better results in terms of memory usage and resource management? In the meantime it’s all about raising awareness …
Raising Memory Awareness
Most importantly I think we need to raise more awareness to these issues to cocos2d developers. One step towards that would be for cocos2d to display a “available memory counter” alongside the FPS counter. I used to patch CCDirector to simply display memory instead of FPS since that was always more important to me. Fellow cocos2d developer Joseph sent me his version to display both - I simply didn’t think of the obvious. So if you’d like to see FPS and available memory next to each other I think you can handle the changes to CCDirector outlined here:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 |
// CCDirector.h, add below @interface: +(double) getAvailableBytes; +(double) getAvailableKiloBytes; +(double) getAvailableMegaBytes; // CCDirector.m, add as appropriate: #include <sys/sysctl.h> #import <mach/mach.h> #import <mach/mach_host.h> [...] +(double) getAvailableBytes { vm_statistics_data_t vmStats; mach_msg_type_number_t infoCount = HOST_VM_INFO_COUNT; kern_return_t kernReturn = host_statistics(mach_host_self(), HOST_VM_INFO, (host_info_t)&vmStats, &infoCount); if (kernReturn != KERN_SUCCESS) { return NSNotFound; } return (vm_page_size * vmStats.free_count); } +(double) getAvailableKiloBytes { return [CCDirector getAvailableBytes] / 1024.0; } +(double) getAvailableMegaBytes { return [CCDirector getAvailableKiloBytes] / 1024.0; } [...] -(void) showFPS { frames++; accumDt += dt; if ( accumDt > CC_DIRECTOR_FPS_INTERVAL) { frameRate = frames/accumDt; frames = 0; accumDt = 0; // the only change in showFPS is this line: NSString *str = [[NSString alloc] initWithFormat:@"%.1f %.1f", frameRate, [CCDirector getAvailableMegaBytes]]; [FPSLabel setString:str]; [str release]; } } |
Raising awareness to leaking Scenes
In addition I highly, strongly and with utmost reinforcement (without pulling out a gun) recommend to cocos2d developers to frequently check your scene’s dealloc methods. Preferably add a breakpoint there, or at the very least add the logging line: CCLOG(@”dealloc: %@”, self). If you want a more visible but less intrusive method you could do something like flashing the screen or playing a sound whenever the last scene is deallocated, so that you get so used to it that when you’re not seeing or hearing it anymore it immediately raises your attention.
If at any time during the development of your project the dealloc method of a scene isn’t called when you change scenes, you’re leaking memory. Leaking the whole scene is a memory leak of the worst kind. You want to catch that early while you can still retrace your steps that might have caused the problem. Once you get to using hundreds of assets and thousands of lines of code and then realize the scene isn’t deallocated, you’ll be in for a fun ride trying to figure out where that’s coming from. In that case, removing nodes by uncommenting them until you can close in on the culprit is probably the best strategy, next to using Instruments (which I haven’t found too helpful in those cases).
I ran into such a problem once because I was passing the CCScene object to subclasses so that they have access to the scene’s methods. The subclass retained the scene and was itself derived from CCNode and added to the CCScene as child. The problem with that: during cleanup of the scene it correctly removed all child nodes but some of the child nodes still retained the scene. Because of that their dealloc method was never called, and in turn the scene was never deallocated.
Chapter 5 - Getting bigger and better
The gist of this chapter will be to discuss the simple game project from the previous chapter. I threw everything into one class, clearly not what you want to do for bigger games. But getting from one-class to real code design is a big step which some hesitate to take. I’ll make that easier and discuss common issues and their solutions, such as what to seperate, what to subclass from and how you can have all the seperated objects communicate with each other and exchange information in various ways.
A big topic will of course be how to take advantage of cocos2d’s scene hierarchy and which pitfalls it may have when moving from a single-layer game to one which has multiple layers and even multiple scenes.
As for the chapter title I’m not so sure if that’ll be it. Maybe along the way while I’m writing I’ll change it. Suggestions welcome!
The chapter will be submitted on Friday, July 30th.
What’s your take on good cocos2d code structure?
Did you ever struggle with cocos2d design concepts? Or the cocos2d scene hierarchy? Or how to layout a scene and divide your game into logical parts? Tell me about it.
I know theses questions are somewhat generic to ask. It’s about the things that don’t feel right but there doesn’t seem to be a better, more obvious way. I think we all know some of those, if you do, be sure to tell me! Leave a comment or write me an email.
Summary of working on Chapter 4 - First simple game
The game I chose to make is called Doodle Drop and features dropping spiders and an accelerometer controlled alien trying to avoid the spiders. All in all it got divided into 8 concrete steps. Lots and lots of code comments, too.
It starts simple enough, adding resources to Xcode and adding sprites. It gets more gameplay-esque when the accelerometer-driven player controls got tweaked to provide acceleration and deceleration of the player object. In contrast, the spiders movements are driven only by actions.
I introduce you to two undocumented features of cocos2d, namely CCArray which is since v0.99.4 used to store all children of a node. The other are the CGPointExtension class which has all the functions normally provided by a physics engine, however not every game should link a physics engine just because one needs those math functions. That’s why CGPointExtension comes in handy.
With the ccpDistance method the collision checks are done. Simple radial collisions, and in debug mode the collision radii are drawn too.
In between the CCLabel for the score got replaced with a CCBitmapFontAtlas, because it killed the framerate. I shortly mentioned Hiero and how to use it in principle but for all the details there was no room. But while I was at it I created the Hiero Tutorial.
At the end of the project I added some polish which isn’t described in the book (too many details) but really adds to the game’s look and feel. The spiders drop, hang in there, then charge before dropping down, all done using actions. I’ve also added the thread they’re hanging from using ccDrawLine. And then there’s a game over label which shows even more action use.
One of the principles I followed is to stay away from fixed coordinates as much as possible. So the project, once finished, did run just fine on an iPad. Although the experience is a different one, there’s more spiders dropping and they drop faster but there’s also more safe space to maneuver to.
Oh and, the game art is all mine. Yes, I know … but Man-Spiders do have just six legs! 
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.
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?
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.
Chapter 2 - Getting Started
This chapter starts with the usual prerequisites. Download and install iPhone SDK and cocos2d. Installing cocos2d Templates. Creating the first project from a cocos2d project template.
From what I already wrote I estimate that will be about one third of the chapter. I think what would be most interesting in this chapter is to talk about general code structure of cocos2d projects. The basic elements like Scenes, Layers and Nodes. How to transition from one screen to another, to see that we’re actually doing something cool with little effort. For that I think the scheduled selectors should also be introduced to time transitions, and one screen might be a Layer which is waiting for touch input to advance to the next screen.
It might also be a good place to discuss cocos2d memory management, like static autorelease initializers, and making sure dealloc gets called when you switch scenes - otherwise you’re obviously having a memory leak.
The goal is to get the reader into a position where he feels comfortable laying out a screen structure in cocos2d. He knows how to initialize objects and how to add and remove them from the scene. The foundation of working with cocos2d if you so will.
What do you think should be in Chapter 2?
Let me know if you think I’m missing anything important. If you don’t have any suggestions then just think about what you would expect from the chapter by reading this description, that might give you some thoughts.
Also I would welcome any tips and the common pitfalls first-time cocos2d developers might trap themselves into. Expert tips are also welcome, those little nasty things or habits which could bite you later on if you don’t consider them from the beginning.
I’m looking forward to your feedback! The earlier the better. Chapter 2 will be submitted next Friday, July 9th.
What’s planned for the Chapter after this one
Just to put Chapter 2 in context, for Chapter 3 I’m planning to talk about essential cocos2d classes and processes. Sprites, Labels, Menus, Actions, etc. It’ll show you how to work with them using small code snippets. The chapter will probably have a “reference” character with various code samples, so that experienced users feel comfortable skipping ahead while beginners still find it easy and encouraging to pick up the details.
I’m writing a book for Apress:
I guess someone wanted to be very precise and thorough. 😀
I will blog about the book’s progress here and when it’s published I will add additional materials so readers can continue their journey here. Since this journey is just beginning - I’m submitting the first chapter aptly titled “Introduction” tomorrow - and writing a whole 400 pages book is an entirely new experience to me, I want to let you in on the journey.
Help me help you by providing feedback to the book’s content as I’m writing it!
For the coming weeks, I will announce the current book chapter title and a short description and ask you what you’d like to see in this chapter. I will make these posts every Friday starting tomorrow until the book is complete. In this post you could start by telling me what you’d expect from this book or what you’d like to see in it just given its title? I guess your answer will be “a lot” given the title’s elongated nature. :p
I hope you forgive me if content updates to this website will not be as comprehensive over the coming months, in favor of writing the book and coding sample games. Plus I’m cooking up something special on the side, but all in due time.
Oh, by the way, if you happen to know what kind of fruit that is on the cover I’d like to know. I could just ask my editor but I’d like to see if we can figure it out without the help from Apress. It doesn’t really look like a coconut to me, which would have been fitting given the subject. If you have any ideas what fruit it is, let me know! It sure looks exotic and it’s definetely not a banana nor a lemon. So what is it? The first to post the correct answer in a comment, together with a link to Wikipedia or some other website as proof, gets a copy of the book for free when it’s out (or $40 now)!
And now for something completely different …
As a side note, the Xcode project files from the Xcode Tutorial are now available for download here. I used to ask you to join my Newsletter but I don’t feel too good about hooking you up with my Newsletter using the project as a dangling carrot, so joining the Newsletter will now be a completely voluntary thing. I only send newsletters for substantial updates and important news, at most once or twice per month, so that’s the thing you want if you are already struggling with RSS overflow.
