Every journey begins with a single step…

Yes I have been working on Faerie on and off for a while now, but this week marks the writing of the first actual lines of production code.  It’s an exciting time.  You have a blank canvas on which you can paint wonderful, clean, elegant and powerful code.  At least that’s how it starts.  Over time entropy, corner cases and flaws in your initial design have a tendency to muddy the code base.  But for now there’s wonder, cleanliness, elegance and the potential for power.

So where do we start?  For me it begins with the layout and structure of the project.  If you’re not a coder, you may want to skip all this technical stuff – I won’t be offended!  If you are a code nerd like me, perhaps this will be interesting to you, or maybe you can see flaws in the way things are laid out, or would like to share how you set up a project.  I’d love to hear what you think!

Stay on target!

The Faerie codebase contains four targets (at least for now).  The first target is the actual Faerie project.  It builds the Faerie app.  This target contains all the resources we use – textures, sounds and music, string resources, nibs and the like.  However this target contains virtually no code, just main.mm.  Why is this?

The answer is unit testing.  All the game code goes into a static library with the exciting name of GameLib.  By putting the code into a static library, it’s possible to unit test all the game code.  And it’s unit testing that comprises the other two targets in my project.  One is a static library containing the the UnitTest++ framework, and the last is an executable target that links the UnitTest++ framework, GameLib and all out test code.  I’ve described this set up previously if you’re interested in the details.  The advantage of setting up the code this way is that our actual app doesn’t need to include any testing code, yet we are able to test the exact library that is used in the game itself.  So the target structure looks like the image below.  Note the final step in the Faerie target, which runs the GameLibTests executable with every build – very handy!

There is one issue we need to address however.  Our nib files need to be in the Faerie target to ensure they’re included in the app itself.  And for testing purposes, all the view controller code is in the GameLib library.  This causes a problem because the linker doesn’t know that it should get the view controller code from GameLib, and so we get errors when the nibs are constructed at run time.  To fix this, it’s necessary to add the following to our “Other Linker Flags” setting for the Faerie target:

-force_load "$(BUILT_PRODUCTS_DIR)/libGameLib.a"

What about the code?

I find it very hard to create a new project from scratch, so I start with the OpenGL template and rip out the stuff I don’t want and reorganise the rest into a layout that suits me  Here’s the basic layout:

These groups in XCode are matched with an identical file layout on disk.  XCode doesn’t require this, but I find it too confusing if they differ.  As you can see, the Faerie folder contains basically no code.  It’s GameLib that has all the good stuff.  Acorn is all the standard code I carry from project to project – code to handle maths, loading textures, playing sounds and more – all that low level stuff.  GameLogic gets all the game specific code, and Views contains all the view controllers for my nib files.  Why the split between GameLogic and Views?  The main reason is that my view controller code is (by necessity) largely Objective-C, while the rest of my code is (as much as possible) pure C++, so it seems reasonable to keep them apart.

The Resources folder contains all the game assets, sorted by type and/or purpose.  By the time the game is done, there’ll be a lot of folders and a lot of files in here, so it’s good to keep them organised.

A simple trick to add a little polish

Here’s something truly simple that you can do in any app for a little extra style.  On startup, our app shows Default.png (or equivalent), and then once the main view is loaded it ‘cuts’ straight to the main view.  Wouldn’t it be nicer if we could smooth out that transition?  It turns out it’s easy to do.  Simply add a UIImageView to your main window, sitting above everything else.  The UIImageView should fill the screen and contain Default.png.  So what happens is that the main app loads and seamlessly replaces the loading screen with an identical screen, but one that we have control over.

Then, it’s a simple case of fading our Default.png image out, revealing the main view underneath, using a bit of code like this in your update loop:

float deltaTime = (float)gameClock->GetFrameDuration();
if (!loadingDefaultView.hidden)
{
    defaultViewFadeOut -= deltaTime / fadeDuration;

    if (defaultViewFadeOut < 0.0f)
    {
        defaultViewFadeOut = 0.0f;
        loadingDefaultView.hidden = YES;
    }
    else
    {
        loadingDefaultView.alpha = defaultViewFadeOut;
    }
}

*UPDATE*

Miguel, the mighty @mysterycoconut pointed out that this could also be done using standard animation calls in UIKit, so here’s an alternate version that gets executed in the viewDidAppear method…

- (void)hideLoadingDefaultViewDidStop
{
    loadingDefaultView.hidden = YES;
}

- (void)viewDidAppear:(BOOL)animated
{
    if (!loadingDefaultView.hidden)
    {
        [UIView beginAnimations:@"Hide loading screen" context:nil];
        [UIView setAnimationDuration:fadeDuration];
        [UIView setAnimationDelegate:self];
        [UIView setAnimationDidStopSelector:@selector(hideLoadingDefaultViewDidStop)];
        loadingDefaultView.alpha = 0.0f;
        [UIView commitAnimations];
    }
}

So what’s next?

I think after all this generic setup, it’s about time to add some actual game code, right?  Well the first thing I like to get going in a project like this is the flow from screen to screen, so that’s the next job on my list, adding the nibs and view controllers for the main menu, game, pause screen, credits and so on.  It won’t be pretty, but the aim is to get all the required buttons and such in place and working so that I can navigate around the app.  I find this to be a nice psychological stage to reach because, once done, I have a ‘complete’ app, and all I have to do is fill in the gaps!

After that, I need to make a key decision – OpenGL ES v1.1 or 2.0?  I think that 2.0 will win out, but I’ll delay that decision for another post!

The story so far…

For convenience, here’s an index for the whole series.

• Part One, Overview of what an automated build is, and why it’s so useful.
• Part Two, setting up a basic build.
• Part Three, automatically versioning and tagging your project.
• Part Four, this article.  An example of a complete, working build.

Running all the time

One thing you want to set up with your build is to have it running all the time in the background.  I found this very helpful article by Jérôme Renard that covers a useful technique.  Read the comments, they’re very handy too!  In an ideal world, Hudson would run happily under all user logins.  And in fact the comments in Jérôme’s article describe how this can be done.  Unfortunately, when it comes to iOS development, the code signing that is done on AdHoc and Distribution builds requires various certificates etc to be present in the user’s keychain.  Setting these up for all users is a pain that keeps on hurting, especially every time you need to update a profile – when you add a new device, for example.

My advice is to just set up Hudson to run under a single user account – either your own developer account, or a special ‘build machine’ account if you have a dedicated computer available.

Hudson-wide setup

Hudson has a number of settings that can be applied to most or all projects.  By following the links to Manage Hudson | Configure System, you can set things such as non-standard paths for source control, default email setup and so on.  In my case, it’s a place to set up email defaults and twitter settings:

You’ll note that I’ve had to set up a non-standard port for email, and that I’ve added my email address as the system admin – if anything funny happens, Hudson will let me know through this address.  While it’s possible to set these on a per project basis, doing it here once just makes sense.

One more thing.  When I was talking about setting up a build from scratch, I’d typically use the ‘Build a free-style software project’ option when setting up a new job.  Once you have a working build, the ‘Copy existing job’ option becomes very useful, and is a huge time saver.  Typically a new build can be up and running in the five minutes it takes to change a few path variables.

The build job itself

OK, so let’s look at the setup for the actual build.  First of all, version control:

There’s nothing particularly unusual here.  I nominate the folder to check out the code into (‘Acorn Money’).  This is not necessary, but feels a little tidier to me.  The main thing to note is that I don’t trust an update and build here – an automated build should always be completely clean.  While Hudson doesn’t offer this out of the box, it does have the ‘Revert’ option to ensure no modified files are included in the build.  If anyone knows of a way to force Hudson to wipe and fetch the project clean from version control each time, let me know, I’d love to know how to do it.

So, no build triggers here.  This is because I want to generate an AdHoc build on an ‘as required’ basis.  Hudson is running on my MacBook, so the last thing I want is scheduled builds kicking off while I’m working.  The ‘Poll SCM’ option is handy for Continuous Integration, while the ‘Build periodically’ option is useful for nightly builds when the machine is otherwise idle.

Right, let’s look at the guts of it now, the shell scripts that do the actual building.  I use several scripts, separated into logical chunks.  They could all be run in a single script, but I prefer the separation here – each script has a singular purpose.  First up, we increment our build number and tag the code in SVN (see part three of this series):

cd AcornMoney
agvtool -usesvn bump -all
agvtool -usesvn tag -baseurlfortag http://acornsvn.no-ip.org:808/acornheroes/svn/AcornMoney/tags
cd ..

Next, the easy part is actually building the code, using an AdHoc configuration:

cd AcornMoney
xcodebuild -project AcornMoney.xcodeproj -target AcornMoney -configuration AdHoc
cd ..

For setting up a Distribution or AdHoc configuration, I generally refer to this cheat sheet, which is great for helping me ensure I don’t miss anything.  Finally, the fun part.  Once a build is successful, wouldn’t it be nice to make it available to all your testers automatically?  With the help of DropBox.com, it’s relatively easy.  Here’s the script:

cd AcornMoney
mkdir Payload
cp -rp build/AdHoc-iphoneos/AcornMoney.app Payload/
zip -r AcornMoney.ipa iTunesArtwork Payload
rm -rf Payload

rm -rf ~/Desktop/Dropbox/Acorn\ Money\ Builds/Latest/*
cp AcornMoney.ipa ~/Desktop/Dropbox/Acorn\ Money\ Builds/Latest/
cp ~/Library/MobileDevice/Provisioning\ Profiles/AcornHeroesAdHoc.mobileprovision ~/Desktop/Dropbox/Acorn\ Money\ Builds/Latest/

if [ $BUILD_NUMBER -lt 10 ]
then
 TMP_BUILD_NAME=AcornMoney00$BUILD_NUMBER
elif [ $BUILD_NUMBER -lt 100 ]
then
 TMP_BUILD_NAME=AcornMoney0$BUILD_NUMBER
else
 TMP_BUILD_NAME=AcornMoney$BUILD_NUMBER
fi

mkdir ~/Desktop/Dropbox/Acorn\ Money\ Builds/$TMP_BUILD_NAME

cp AcornMoney.ipa ~/Desktop/Dropbox/Acorn\ Money\ Builds/$TMP_BUILD_NAME/
cp ~/Library/MobileDevice/Provisioning\ Profiles/AcornHeroesAdHoc.mobileprovision ~/Desktop/Dropbox/Acorn\ Money\ Builds/$TMP_BUILD_NAME/

It may look like there’s a lot going on here, but most of it is just copying files around.  First of all we create an .ipa file (just a zip file with a different extension) which contains our build plus an ‘iTunesArtwork’ png image – otherwise the App icon doesn’t show up in iTunes for an AdHoc build.  Next up, we remove any existing ‘Latest’ build folder in our Dropbox folder.  Then we create a numbered folder for this build (e.g. AcornMoney08) and copy AcornMoney.ipa into this folder and the latest folder.  We also copy the provisioning profile from ‘~/Library/MobileDevice/Provisioning Profiles’, as it will be needed by our testers.

From here, Dropbox takes care of syncing this folder with anyone who is sharing it.  Our testers get a notification and a new build delivered to their own PC!  The post-build actions are fairly uninteresting, all I have set currently is email notification on a failed build.  Even this is slightly overkill, as for an AdHoc build I’m normally sitting at the machine watching the build anyway.

That’s it, a fully working build.  With Hudson, it’s possible to set one of these up with just an hour or so tinkering around.  Once you have a working build as an example, making a new build can be just a few minutes work.  Give it a go and let me know how you get on!

Acorn Money update

For those of you interested in Acorn Money, our money tracking App, we’re still in review.  Sam made some significant improvements to the graph rendering code and we felt the best thing to do was to pull the submitted build and re-submit.  Unfortunately this sends us back to the end of the queue.  Still, we’re hopeful Acorn Money will be available in the next couple of weeks.

This post is part of iDevBlogADay, a group of indie iPhone development blogs featuring two new posts per day. You can keep up with iDevBlogADay through the web site, RSS feed, or Twitter.

It must be the time of year or something, but obviously a few developers have been evaluating their progress and plans for the future.  Not afraid of being a slave to fashion, it seemded like a good time to have a look at the progress of Acorn Heroes over the past year.

In our case this navel gazing has been triggered by the fact that we’re due for our first payout from Apple on September 2nd.  Yep, you read that right, our first.  That may sound like a fairly mediocre result, and in some ways it is.  But there’s also a ray of hope there.  Read on…

Some context

Sam and I are both fully employed on other jobs.  We both have three kids, a wife and a mortgage.  The good side of this is that we’re relatively stable and don’t need to be successful on the App store just to survive.  The flip side is that anything we do is done in a spare hour here and there at the end of the day, family commitments allowing.

Past

Goo! (App store link) was released back in January, and is a fairly niche application for maths nerd who like playing with cellular automata, or possibly two year olds who like the pretty patterns (my youngest is a great example of this).  Despite that it’s been ticking over quietly averaging about 2-3 sales a day.  While it won’t make us rich, or let us quit our day jobs, it will cover the cost of our web hosting and dev license for another year.

iDevBlogADay has been (and continues to be) a wonderful experience – the requirement to write each week is a great motivator and has introduced me to an expanded network of great Indie developers.  If you haven’t subscribed to the iDevBlogADay feed yet, your missing a ton of great content.  Here’s a handy link.

Present

Sam (the quiet one) is doing wonderful things with Secret Project M. It’s only secret because we haven’t talked about it yet – but we should be announcing M officially soon.  We’re in what can probably be described as an ‘early beta’ stage – polishing features and UI and squashing bugs.

Faerie is a promising game idea that I’m looking to develop fully.  Basic gameplay is solid and we’re looking to build a solid, appealing game that will appeal to people of all ages.  Sneezies and Robot Unicorn Attack are great examples of the kind of experience we’re aiming to replicate.

In my day job, I’ve been part of a team working on data capture for high performance athletes – there’s a good story covering what’s been going on here.

Future

So, what does the future hold?  It’s busy, that’s for sure.  We’re aiming to finish M in the next month or two.  Having a second App on the store is a huge milestone for us, especially as Goo! was a proof of concept as much as anything.  To say we’re excited is an understatement.

Faerie is on hold for a little while, because I’ve taken on full time contract work until the end of the year.  I can’t reveal many details at the moment, but we’ll be creating a game for iOS that is linked to a major TV channel.  I’m hopeful that I can cover our progress over the next three months or so.  We’re aiming for a November/December release.

So, interesting times ahead with lots going on.  Sam and I would like to take this chance to thank everyone who’s bought Goo!, followed our blog or provided advice on working in the magical, mercurial world of iOS development.  Your words of encouragement mean a lot to us!

Just a quick note to say that I’ve switched our RSS feed over to Feedburner. The new feed is http://feeds.feedburner.com/AcornHeroes.

What does this mean for you? Actually, nothing. The old feed will still work exactly as it has, this is just a behind the scenes, making it easier for ourselves sort of update.

So why am I saying this? Well, if your a regular subscriber (thank you!) then if it’s not a hassle, moving over to the new feed will make our lives a little easier, and helps make this site just a little better.

If you’re not a subscriber, then I’d like to offer you this chance to subscribe. We aim to offer useful, relevant information to independent game developers with a focus on iOS development in particular.

So, if you want to add or update our RSS feed, the new link is http://feeds.feedburner.com/AcornHeroes – but once again, nothing will break if you don’t, so feel free to do nothing at all

Dan Grigsby over at Mobile Orchard has put together a screencast that explains the process of provisioning an iPhone / iPod touch.  It’s well explained, simple to follow, and a very handy resource to have around.  It’s a free download for the next week, after that it’ll be US$5.  So if you’re a new developer, or if this is something that you’re a bit unsure of, grab the screencast while it’s free.

So it’s no surprise that there’s a new contender for my time.  Although what it is may seem a bit odd.  I was recently reading Cliffski’s blog and came across a piece he wrote about Google Analytics. Finding out what was possible was a pleasant revelation.

In short order I’d signed up on the main page, dropped the relevant script onto our site.  A tip for WordPress users, log in as admin, add a new Text Widget and put the script in there – simple.  Then came the hard part – waiting for up to a day to know that it’s all working properly.

The depth of information available is astounding.  The fact that we actually had people visit our site was comforting!  But beyond that we can see how visitors came to our site, roughly where they came from, what pages on the site they spend time reading and a whole heap more.  I’m hooked.  There’s no need to check the data several times a day, but it obviously tickles the nerd centre of my brain in a good way, so I check in regularly.  

After a week there’s not enough evidence to draw any real conclusions, but here’s a few interesting snippets:

• We’ve had 48 unique visitors.  When we hit 100 I might make a cake to celebrate.
• Those people typically view a couple of pages, of which my font rendering post is a clear favourite.
• Hello to the USA, Australia, UK, India, Hungary, Poland, Latvia, Singapore and South Korea!
• There’s a reasonably even split between people arriving directly, finding us via a search engine or being referred from another site.

The main thing that has stood out for me is that the technical posts are the most popular, so I will endeavour to get more out as soon as I can.  Current candidates are articles about texture atlases and  particle systems.

On that note, I can say that the particle system I’m working on is coming along slowly but well, stay tuned I’ll post more details,screen shots and code when there’s enough to be of interest.

Here’s how it went down for us:

• Create company on the 9th of May.
• Submit for application for developer program on the 10th.
• Email from Apple asking for our Certificate of Incorporation on the 12th.
• Finally get a chance to fax off the Certificate on the morning of the 14th.
• Get a phone call / email from Apple about noon.
• Purchase license about 5 minutes later.
• Prepare to wait ‘up to 48 hours’ for activation code.
• It turns up 4 hours later.
• Go to the Apple’s iPhone Dev Center and remember to log out and log back in again to see the update.
• Done, we have the keys to the Magic Kingdom.

That’s right, the bulk of the process happened in a single day.  Start to finish was only five days, two of which were a weekend, and one of which was lost due to my inability to get close enough to a fax machine.  Thank you Apple, you’ve made my week, possibly my month.

Now admitedly we haven’t sorted out all the financial details yet, but we don’t have an application to sell yet either, so I’m not too worried.  What we do have is the ability to deploy applications to an iPhone or iPod Touch now, and the first time you do that is a little magical

Sam and I also had a design session last night where we started seriously planning our first two applications.  More on that later.

Setting up a company in New Zealand is a simple process.  There’s a useful (though not particularly pretty) web site that guides you through the whole process.  The site guides you through a bunch of steps; reserving the company name, nominating contacts / directors, allocating initial share parcels, getting a tax number and of course paying your NZ$160 bozo filter.  At the end of it you get a Certificate of Incorporation that you can print out and use to bolster your ego and impress your friends.  It was all done in about half an hour, and the only thing you need is your tax numbers.

We wanted to get the company up and running before we joined Apple’s Developer Program, as we’ve heard that starting with a personal license and migrating it to a company one is a real pain.  Once we had a company registered, the next step was to see the nice people at KiwiBank to sort out a bank account.  Once again, it couldn’t have been easier, and now we have a business account that can accept all the millions we plan to make – or at least enough to help cover getting a new stove.

Our enrolment in the Developer Program is underway, a process which is apparently taking up to six weeks at the moment.  No doubt there’s a blog post to come from that process too!