Example ARC project. Pretty awesome.
Therefore I decided to enable ARC in all twelve standard cocos2d Xcode project templates for both cocos2d versions (v1.1 and v2.0), both platforms (iOS and Mac OS), both physics engines (Box2D and Chipmunk) and publish them on github.
You can download the ARC-enabled cocos2d template projects either as ZIP file or TAR file.
While Cocos2D is compatible with ARC, simply enabling ARC in the project’s Build Setting will throw several hundreds of errors in your face. Cocos2D doesn’t provide ARC-enabled project templates. Thus this tutorial about how to enable ARC in a newly created Cocos2D Xcode Project.
While none of these steps are overly difficult, you’ll notice there’s plenty of steps to perform. Unavoidably, and on the off chance you don’t already know, I’d like to recommend Kobold2D to you if you want to write ARC enabled Cocos2D apps. Because none of the steps below, really zero, zilch, nada, niente, keine are necessary to enable ARC in Kobold2D. That’s because it ships with 15 template projects all of which have ARC enabled out of the box. And Kobold2D 2.0 with cocos2d-iphone 2.0 is just around the corner.
Self-advertisment aside, these steps are tested with cocos2d-iphone v2.0 but should also work with cocos2d-iphone v1.1 - but admittedly I haven’t tested the process with the v1.1 version. If you find anything that’s not quite working with v1.1 please leave a comment. Preferably with the solution, that’ll be awesome!
UPDATE: I released a video version of this tutorial: Continue reading »
This quick comparison sheet gives you all the info to decide whether to use Cocos2D 1.x or Cocos2D 2.x. Contrary to most programs, a higher version number doesn’t infer “better” or “more”. There are pros and cons for both versions.
At the time of this writing the decision really only boils down to whether you want to use shaders and whether you must be able to deploy your app to 1st & 2nd generation devices. See for yourself, it’s that simple:
Cocos2D v1.x(+) compatible with all iOS devices |
Cocos2D v2.x(+) OpenGL ES 2.0 shader programs |
All other differences to this day are minor, and most new features and bugfixes have been migrated back and forth between versions. For beginners I strongly recommend using v1.x as there’s a lot more documentation available for this version. Those who have no interest in writing shader programs can also safely use the v1.x branch without missing out.
Without further ado:
Download Kobold2D Preview 4
Enjoy it!
The Most Important Changes & Additions: Continue reading »
The Goal
Kobold2D users should never have to run a bash script, ever. Any project or asset management task most users will want to perform should be done with a visual tool.
The Problem
I mentioned before that I had problems turning the Kobold2D project templates into the Xcode 4 Project Template format. In fact, it turned out to be impossible due to the nature of Kobold2D’s workspace setup.
Since I want to have a wide variety of project templates in Kobold2D, and definitely more than the three rudimentary templates that cocos2d-iphone offers, I needed some way to allow users to start new projects based on a template.
The Solution
What I came up with is the Kobold2D Project Starter Tool:
Simple and elegant. This tool scans the projects in Kobold2D templates folder, which are regular Xcode projects with a common naming scheme (eg. _Hello-Kobold2D-Template_), and presents them to the user including a description.
Select a project template, give it a name and click Create. The tool will copy the template project to the Kobold2D folder next to all the other projects. All occurrences of _XXXX-Template_ are renamed to the user supplied project name (which is cleaned to remove illegal characters). Then the project is added to the Kobold2D.xcworkspace which the tool will open right away.
The Benefits
I think the biggest benefit by far is that anyone can turn his or her Xcode project into a template, simply by following the naming scheme. Anyone can create and distribute their own Kobold2D project templates.
Note: in the screenshot there are only 7 templates listed. I’ll definitely add more for the Kobold2D v1.0 release, most will be based on projects discussed in my Learn Cocos2D book. The first preview version (v0.9x) of Kobold2D will be available in about two weeks.
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.
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.
