Today I completed the first draft of the Kobold2D chapter which will be in the second edition of the Learn Cocos2D book. In that chapter I’m also giving you an introduction to cocos3d, the official 3D add-on library for cocos2d. I ported cocos3d’s Xcode project template to Kobold2D and spiced it up a little with some cocos2d nodes in the back- and foreground:
Notice the “incoming network connection” warning. This is caused by the iSimulate library which is distributed with Kobold2D and activated by default for Simulator builds. You still need to buy the iSimulate App to benefit from it though. If you don’t you can also choose to ignore the dialog or simply disable iSimulate by commenting out a line in the project’s BuildSettings-iOS.xcconfig file.
I’ve also had great fun with the augmented reality option that the cocos3d CCNodeController class provides. And setting it up is one line of code. Here’s the “camera as live background” demo in action:
Since a picture doesn’t really do it justice, here’s a video:
Admittedly it could run a little faster on my iPhone 3G. It’s pretty taxed and averages around 20 fps with the camera background view and rendering a 3D model. My iPod Touch 4 averages at around 40 fps and it feels a lot smoother.
Kobold2D Todo List
One of the biggest items on my todo list for Kobold2D is to design the website and get rid of the “coming soon” page. This includes setting up the wiki and filling it with content, documentation for the most part. And, well, paying $150 each month because I don’t see any alternative to using Confluence. I want to enjoy working on documentation, and I want you to enjoy browsing and reading it.
I also want to create more template projects. Currently, as you can see in the first screenshot, there’s Hello Kobold2D (iOS & Mac), Hello Cocos3D (iOS) and Hello Cocos2D-X (iOS). I want to add two more templates, one for Chipmunk with SpaceManager (iOS & Mac) and one for Box2D (iOS & Mac). I also want to add the projects from my book as project templates, namely Doodle Drop, the Shoot ‘em Up game, the Orthogonal and the Isometric Tilemap projects, and the Cocos2D With UIKit project (all iOS).
Even though Kobold2D won’t have Xcode 4 Project Templates I still want to give you a quick and easy way start a new project based on one of the template projects. Notice the distinction between “project template” (those in Xcode’s New Project dialog) and “template project” (a regular, already existing project). I started writing a tool that allows you to create a copy of an existing Kobold2D template project and rename it, so that the workflow is just as convenient as doing it within Xcode. It works for the specific template I tested it with, but I still have to design the user interface and make the code fail-safe.
In case you wonder why Kobold2D won’t have Xcode Project Templates: they are not nearly as powerful as they would have to be. And they’re a pain in the rear to create and maintain without some tool support. But worst of all, you have no way of including files in an Xcode 4 project template that must not be added to the Project Navigator. Like, for example, .xcodeproj files.
The Cocos2D Installer has been superseded by Kobold2D!
Since you’re looking to install Cocos2D, you may be interested to hear about the Kobold2D game engine. Kobold2D is designed to make Cocos2D developers more productive. Of course it comes with an installer, and includes Cocos2D.
Original Post
With the release of the unstable cocos2d-iphone v1.0.0 rc3 version today I’ve updated the Cocos2D Installer to include this new version, as well as an updated version of Cocos3D (v0.5.4). The installer will install the Xcode templates for you for both cocos2d and cocos3d in both Xcode 3 and Xcode 4 versions.
Download the Cocos2D Installer (66 MB)
The Cocos2D installer includes cocos2d-iphone v0.99.5 (stable) & v1.0.0 rc3 (unstable) and cocos3d v0.5.4.
Cocos2D/Cocos3D will be installed to the user’s Documents folder in appropriately named subfolders. You can move these folders after installation to another folder without breaking anything.
Upgrading cocos2d-iphone is a recurring issue for many developers but since it happens so infrequently during the lifecycle of a project, there’s just no routine to follow. Eventually you might want to upgrade cocos2d-iphone, so the question arises: how do you do that with the least amount of trouble?
As I’m going through the process of updating over 70 (!) Xcode projects for the second revision of my Learn Cocos2D book, I thought I should outline the steps to upgrade an existing Xcode 3 project which uses cocos2d-iphone v0.99.x to a Xcode 4 project that uses cocos2d-iphone v1.0.x.
Prerequisites: software update
Obviously, you want to download the latest cocos2d-iphone version and unzip it to any directory. Just remember where you unzipped it because that’s where you’ll copy the new library folders from.
You also want to make sure you’ve upgraded to Xcode 4 by now, by installing the iOS 4.3 (or later) SDK, if you haven’t done so already.
Caution: Make sure Xcode is closed during the first steps.
Step #1: delete libs folder contents
In your project’s folder, in this case DoodleDrop03, select all folders in the libs folder and delete them without mercy:
You’ll end up with an empty libs folder. In other words, don’t delete the libs folder itself or in case you did, make sure you re-create the libs folder.
Caution: The reason why I delete all the libraries in the libs folder instead of simply overwriting the libraries with new ones is simple: you can expect the updated cocos2d-iphone version to have removed or renamed some files. By first deleting all libraries you can be sure that no “zombie files” exist which are no longer used but might still be compiled when you later re-add the libraries. Such zombie files would screw up the build process and generate errors like “Duplicate defined symbols” and other such mishaps.
Step #2: copy the library folders
The first thing you’ll notice when you want to upgrade the libs (Box2D, Chipmunk, cocos2d, CocosDenshion, cocoslive, FontLabel and TouchJSON) is that they’re in different folders in the cocos2d-iphone project that you’ve downloaded and unzipped.
Make sure you select the exact same folders that are selected in the screenshot below:
This difference in folder layout can be a bit confusing. What you need to be aware of is that the Box2D, Chipmunk, FontLabel and TouchJSON folders are in the external folder in the cocos2d-iphone project. Furthermore, the Box2D folder that you should copy is a subfolder of Box2d. Note the difference in capitalization of the letter D. You want to copy the folder with the uppercase D: Box2D. The same goes for the CocosDenshion folder, you should select the CocosDenshion folder inside the CocosDenshion folder.
Caution: Make sure you don’t select the Box2D Testbed folder - if you do and copy that as well, Xcode 4 might lock up building the project, consuming 100% CPU power and requiring a force quit to shut it down.
Note: If you use only Chipmunk or Box2D physics, or neither of them, you can skip copying these folders of course.
To complete the copy opertation, go to the libs folder and paste the copied library folders so that you end up with a libs folder that looks exactly like the image in Step #1.
Tip: If you prefer drag and drop you can just drag the selected folders from one Finder window to another onto your project’s libs folder. This may be easier to do but you should remember to hold down the Option key while dropping so that you actually copy the folders instead of moving them. The copy operation is indicated by the green + icon underneath the cursor as you drag & drop while holding the Option key.
Step #3: Remove Library References
Open your project in Xcode 4 now.
Select all groups under the cocos2d Sources group and hit Backspace to delete these groups (or right-click and choose Delete). You will be prompted with a dialog like in the screenshot below.
Make sure you select the default option Remove References Only to avoid deleting the new library folders you just copied:
Once you’ve removed the libraries groups, the cocos2d Sources group should be completely empty. You just got rid of all the old references, saving yourself from any potential compilation errors caused by references to files which may not exist anymore.
Step #4: Add Library Folders
Next you want to re-add your library folders. Select and right click the cocos2d Sources group and select Add Files to “NameOfYourProject”…:
Browse into the project’s libs folder and select all the library folders that you need in your project.
You may have noticed that my project doesn’t use any physics engine, so I decided to not add them here. If you do use Box2D in your project you would want to also select Box2D of course. Likewise if you use Chipmunk.
Note: While it’s not a problem to add both physics engine folders, doing so might increase your App’s size.
Now, here’s where you need to be careful with the options! You want to make sure they’re set exactly as in the screenshot below. Most importantly, when adding files Xcode will default to add the files to the project’s main target (in this case DoodleDrop) instead of the cocos2d libraries target.
Make sure that only the cocos2d libraries target is selected to avoid any build errors:
Step #5: Build it!
You should now try and build the project. If you’re lucky, there won’t be any errors and you can continue with your work.
But most likely, depending on your project’s complexity and the changes made to cocos2d-iphone, you may have to fix any build errors that occur. Most of them are likely to be caused by classes that have been renamed or functions that have been deprecated. In this case you’ll have to find out through the API Reference and release notes what the changes are and how to fix them.
Fixing the “missing base SDK” message
One common issue that occurs specifically to older projects is the “missing base SDK” error. I think it was the Xcode version introduced with Mac OS X Snow Leopard (released Aug. 28th 2010) that eventually fixed this dreaded issue by adding a “latest iOS” option for the Base SDK Build Setting.
If you see a message like this (especially if it gives you a compile warning or error):
You should change the Base SDK Build Setting of your project to use the “Latest iOS” setting:
Note: In some cases it may be necessary to close Xcode 4 and re-open it to make the “missing base SDK” message go away.
Correctly Inheriting Build Settings
Normally, all targets in Xcode inherit the Build Settings of the project by default.
However, once you’ve made any change to any Build Setting at the target level this Build Setting will no longer inherit changes made to the same Build Setting on the project level. The default reaction by many developers is often to bite the bullet and check and re-check the Build Settings of the project as well as all targets, and to make the same change as many times as you have targets in your project.
Don’t do that, there’s a better and easier way!
You can have a Build Setting at the target level to default back to inherit the Build Setting defined at the project level. Likewise a Build Setting at the project level can be set to inherit from the OS default setting. In the screenshot below I have purposefully changed the Build Setting at the target level:
To have it default back to the project setting, which is Latest iOS (iOS 4.3) all you need to do is to select that Build Setting and hit the Delete key:
Tip: Switching from the Combined to the Levels view when reviewing the Build Settings makes it easy to see which Build Settings are inherited and which aren’t. You’ll also notice that any Build Setting that has been changed at the current level and doesn’t inherit its value anymore is printed in bold letters.
That’s it!
Happy coding with your newly updated cocos2d-iphone project! This upgrade tutorial will also be printed in the second revision of the Learn Cocos2D book.
Tip: With Kobold2D it will be even easier to upgrade your project because a simple copy & paste of the files in the kobold2d folder will suffice. If there are ever any additional steps to follow we’ll describe them in detail of course.
As promised a while ago my Xcode 4 Template Documentation efforts have finally produced a result. Please refer to the product page for more information.
I’ve put in roughly 70 hours. Might have been even more, I didn’t keep track. I would appreciate your support by purchasing the documentation!
I also checked again if any new source of information on Xcode 4 Templates has come up, but couldn’t find any new sources. As of today and roughly 4 weeks after I started with my Xcode 4 documentation endeavour, there’s still very little documentation about Xcode 4 templates on the net. The following are the only external sources I referred to:
- Minimal Project Template with example
- List of replacement placeholder strings
- Solution on how to place files in subgroups
The marketing dude in my mind tells me I should probably mention that the information you get from the above links is just a fraction of what you’ll find in my Xcode 4 Template documentation. 
Happy Easter!
Or to be politically correct: Happy Holidays! 
What you’ll get in bulletpoints:
- Five tutorials on how to create File and Project templates
- Extensive reference for all known TemplateInfo.plist items (keys) and settings
- Explanation of the placeholders (eg ___FILENAME___) and variables (eg ___*___)
- Frequently Asked Questions answered
- Many tips and tricks
- Total of 70 pages of documentation (PDF) from 70+ hours of experimentation
- File and Project Template example files
Synopsis
This unofficial but comprehensive Xcode 4 Template documentation explains how to create File and Project Templates for Xcode 4. Xcode 4 uses a template format significantly different from the one used in Xcode 3, which renders all previous information on Template creation useless. The new format is also much more complex and allows for greater flexibility, for example a template can now consist of multiple inherited templates.
This Xcode 4 Template documentation first gives you a quick overview what File and Project templates are. Step-by-step tutorials show you how to create your own File and Project Templates. In the reference section the format of the TemplateInfo.plist and related files are meticulously documented. Finally there’s the Frequently Asked Questions (FAQ) section with answers to common questions. The documentation is fully hyperlinked so that you can quickly look up keywords in the reference section. Several example files for File and Project Templates help you get started and can be used as the basis for your own templates.
Available for free
The documentation is now available for free:
Download Xcode 4 Template Documentation (ZIP, 6 MB)
Disclaimers
This is not official documentation. I can not guarantee that the documentation is 100% correct, much of the information was found out through lots of trial and error. Nevertheless this documentation contains a lot more information than what is currently available on the Internet.
THE DOCUMENTATION IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE DOCUMENTATION OR THE USE OR OTHER DEALINGS IN THE DOCUMENTATION.
Today I tweeted:
“How to be efficient? Don’t try to master the art of perfection.”
That seems to have caught some attention. I must admit it wasn’t entirely devoid of any meaning to my work. For all the time when I was an actual employee and someone else was paying me to do a certain job within a specified time frame as good as possible, it remained an elusive notion that one day, you want to do a job “right” for once. Because there’s always either time or budget cutting into what’s possible or worse what’s reasonable.
I always considered myself to be a pragmatic, and while I liked the notion of one day doing one’s work as good as one possibly can - a mantra some of my colleagues were more keen than others to repeat - I accepted that it would never happen. That was until I became responsible for my own work and financials. I recently started digging into the Xcode 4 Template system, at first out of interest and requirements for the Kobold2D project, and then to make quality documentation for the new Xcode 4 template system. I think that was about 3 weeks ago now, and recently I noticed I’m not going very far, I keep finding the roadblocks and dead ends and generally quirks and issues which end up in countless of hours doing nothing but trial & error with little results to show for.
And there I was, fighting with myself trying to figure it all out - I mean literally everything. And it was getting harder to finish the job because it became more and more demotivating not being able to find a good (or even a working) solution to my problem.
How not to get the job done, after it’s done
I fell to the elusive thought of documenting the Xcode 4 template system perfectly. I couldn’t succeed because almost by definition you can’t perfectly document a system that is in itself imperfect, flawed, incomplete and merely designed to be used for the things it is used for, no more no less. It’s not even designed to be used by others, or it would have been documented by Apple. I now have a very good understanding of why it was never documented, it just makes sense. My suspicion is that they don’t even edit the templates manually but instead rely on tools to do most of this job. And there seem to be a couple bad hacks in there too.
I had to accept that I’ll have to look for other ways for Kobold2D users to start new projects because of several technical limitations of the Xcode 4 template system: it can’t deal with cross-referenced projects and it’s unbearable for projects with hundreds of files. One of the important goals for Kobold2D was to provide a variety of meaningful, working project templates. Very simple demo games. They’ll have to be created somehow, and sadly I had to come to terms that this won’t be possible within Xcode (4) and has to be done through some other means (and ideally not manually).
Trying to find a solution for Kobold2D project templates kept me working on the documentation even though I should have realized that I have already documented way more than what most people would need for their file and project templates. I couldn’t stop looking for a Project Template solution for Kobold2D, it seemed so close and other solutions so far - so I didn’t even spend time considering those other solutions. Awww, the horror of working alone. No one to kick your butt in the right direction, away from perfection and towards getting the job done.
Decision
So today I decided that I’ll wrap up the Xcode 4 Template documentation I have so far, which is quite a lot nevertheless (currently 57 pages as PDF), and then start selling the document for $10 instead of $15 because it’s not as complete as I intended it to be. Watch for it in the next few days. I’ll let you know.
I have updated the unofficial Cocos2D installer to include the cocos2d-iphone-v1.0.0-rc version so that you can use the Xcode 4 templates. I also added Cocos3D so that you don’t have to run its install scripts anymore.
The installer now installs the following folders to your ~/Documents folder:
- cocos2d-iphone-0.99.5 (latest stable)
- cocos2d-iphone-1.0.0-rc (latest unstable)
- cocos3d-0.5.3 (latest beta)
Warning: Project Templates are buggy!
Depending on Cocos2D/3D version and the version of Xcode, you’ll notice that some of the project templates will not compile without manually fixing some compile errors. This has nothing to do with the installer, the same thing happens when you install the templates manually with the .sh scripts.
For example, the project templates for cocos2d-iphone-1.0.0-rc do not work in Xcode 3 - the ones for Xcode 4 work fine. The Cocos3D project template does not work out of the box in Xcode 4, you have to manually copy and add the Cocos3D files (refer to the readme for more info). The version for Xcode 3 works fine.
Based on the Xcode version you currently use for developing new Cocos2D projects:
- Xcode 3: use the Cocos2D v0.99.5 and Cocos3D Project Templates to start new projects. You can manually update to Cocos2D v1.0.0 afterwards.
- Xcode 4: you will have to start with Cocos2D v1.0.0 (rc). If you want to develop Cocos3D applications, refer to the readme to learn the manual steps involved in creating a working Cocos3D project.
Xcode 4 Template Documentation
UPDATE:
You can get the Xcode 4 Template Documentation here!
The Xcode 4 Template Documentation has grown to nearly 40 pages (PDF) now, with only a few images and just reference material. The reference materials are nearly complete, including placeholders, variables and explanations for the use of every key available for Xcode 4 templates and a FAQ section. I still have to add the step-by-step tutorials (including example templates) for creating your own File Templates and Project Templates, and final proof reading and corrections.
Because the Xcode 4 Template Documentation has grown so big and I’ve already invested 50+ hours in it I want to try an experiment to see if creating documentation at this level of detail is sustainable. I’ll charge a small fee for access to the document, the standard price will be $15 and I’ll start selling it at an introductory price for a short period of time.
If this works out well in terms of revenue vs time investment I will likely offer more such in-depth documentation in the future. I was thinking that 50+ sales per month at $15 is a reasonable goal, and at this rate it would certainly be a welcome incentive for writing more documentation - next to me being generally inquisitive and interested in digesting challenging and diverse subjects.
I think the success of my book also ought to tell me that I can provide such in-depth treatments of game development topics. There’s certainly a lot of need for documentation on Cocos2D in general, but also there’s a big gap in general between what online documentation and tutorials offer (which often are only written for absolute beginners and/or to capture search engine traffic) versus the need of developers to learn more about a challenging niche subject in detail, including hard facts, recommendations, tips and tricks.
Cocos2D Podcast: coming soon …
Mohammad Azam aka @azamsharp recently approached me with the idea of creating a Cocos2D Podcast series. Azam has a lot of experience with creating podcasts and screencasts for the .NET crowd, and he has been a Cocos2D developer for about 6 months now with 4 kids apps already published to the App Store.
Two weeks ago we had a first dry run using Skype and liked the results, so we’re ready to record our first podcast this weekend if nothing gets in the way. I’m excited to try and see where we can take the Cocos2D Podcast and how you will like it.
The first podcast will be an introduction about ourselves and how we ended up working with Cocos2D, before we move on to trending topics in the Cocos2D space. If you have a suggestion for what we should discuss, or if you have a particular question that you like to get answered, please let me know (write a comment).
An apology
Lastly I wanted to apologize for missing last week’s update and not having much to report on this week. I was sick with a bad cold for the last ~10 days so nothing much happened in terms of Kobold2D or the Xcode 4 Template documentation. I’m still working on both of course.
I’m also responding to fewer and fewer emails, comments and forum posts as I’m getting swamped with them while spending a lot of time on other tasks. I realized I have to face the fact that as I gain popularity (much of it thanks to my book) I can no longer tend to everyone. Instead I’ll focus on listening in and providing value for a greater number of developers rather than responding to individual request. I’m sorry and I hope you understand.
