One such example is generating a build for ad-hoc distribution to beta testers.  We could create a build by hand, but if we forget to increment the version number in our project, then our testers won’t be able to update from a previous build unless they delete the old build by hand off their devices and iTunes – definitely a pain for people you don’t want to inconvenience.

Also, imagine the scenario in a couple of weeks when a tester notifies you of a serious bug they’ve found.  Chances are the code you have now is quite different to the build they have.  Can you get back to that point in the code easily?

Fortunately Apple provide us with a handy tool called agvtool that can handle these situations for us.  It’s a command line tool, so it integrates nicely into Hudson.  But first let’s look at agvtool on its own, and see what we can do with it.

agvtool

In order for agvtool to do its magic, we have a few things to set up in our project first.  Most of the steps here are described in detail by Jamie Montgomerie on his blog.  Briefly though, we will use two different version numbers – a release version and a build number.  The release version is our “marketing” number – what our clients see (“Now updated to version 1.2!”).  Our build number is for internal use, and will connect a given instance of our App to a specific tagged version of our code in source control. To test this, I created a simple OpenGL project in Xcode and added it to SVN as a starting point.  The only modification I’ve made to it is to add a label on top of the GL view.  We will use this later to display our build number for testers.  Note that SVN is not necessary for using agvtool, but it will give us a few nice options down the track.

So, following Jamie’s instructions, we:

1. Open our project’s PROJECT_NAME-Info.plist file and set the Bundle version to 1.  This represents our build number.
2. Ctrl (or right) click on the plist and choose Add Row.  From the options presented, select Bundle versions string, short and set its initial value to (say) 0.1.  This is our release version.
3. Ctrl (or right) click on the project in the Groups & Files window, and select Get Info.  Make sure you’ve selected All Configurations and find the Versioning section, near the bottom.  Set the Current Project Version to match you build number – 1 in our case.  Set the Versioning system to apple-generic.

OK, not too painful and we’ll never need to touch these bits again!  Let’s test our a few things.  Open up a terminal window and cd to your project directory.  We can use agvtool to tell us both the current build and release version numbers (agvtool calls them version and marketing version respectively):

You should see the build number (agvtool what-version) and release version (agvtool what-marketing-version) that you entered into the project settings.  Now, using agvtool we can also update our build and release version numbers.  Note that doing this modifies your project, so ensure it’s either not open in XCode or everything has been saved – otherwise you may lose changes to your project such as settings or newly added files. So, to increment our build number we use:

agvtool bump -all

On the slightly rarer occasion that we want to adjust our release version, this can be done as follows:

agvtool new-marketing-version 0.21b

You can use the agvtool what- command to verify what’s going on here.  Note that our build number is automatically incremented by one using the bump command.  Our release version is in fact a string, and we can supply whatever we want there, in this case 0.21b.

Assuming you’re paranoid like me, now is a good time to check this into source control as we have all the basics covered.

Open the project in XCode and build it.  XCode will now automatically generate a .c file as part of the build.  In my case, these were found at:

build/AutoVersionTest.build/Debug-iphonesimulator/AutoVersionTest.build/DerivedSources/AutoVersionTest_vers.c

You don’t need to even open this file, or include them in your project (that happens automatically).  This file declares two variables, a version string and number that correspond to our build number.  We can put them to good use.  In my sample project, I’ve declared the build number as an external variable in my App delegate:

extern const double AutoVersionTestVersionNumber;

And then in my application: didFinishLaunchingWithOptions method I’ve used the build number on the label I added earlier:

versionLabel.text = [NSString stringWithFormat:@"Build: %1.0f",AutoVersionTestVersionNumber, nil];

Now when testers run my App they’ll see something like this:

Now, a tester can easily identify the build they’re running when giving me feedback.  By the way – if anyone know an easy way to get at our release version number in code, please let me know!  What we need now is a simple way to tie that back to a specific version of our code…

Tagging in SVN

Note, this also works with CVS as well, however while there are good arguments for not moving to a more modern system like Git or Mercurial, there’s no good argument for sticking with CVS.

agvtool has the ability to update our version information and then commit the changes, simply by adding the usesvn tag like so:

agvtool -usesvn bump -all

Nice.  But it gets better.  We can then tag these changes to make getting back to them simple:

agvtool -usesvn tag -baseurlfortag http://URL/to/svn/AutoVersionTest/tags

The -baseurlfortag option specifies where the tag should go.  After this operation, you’re SVN repository should look something like this:

Now, when you receive feedback from a tester it’s a simple matter to check out the tagged code and you can track down issues with the same code base your tester was using.  Note that the folder specified by the -baseurlfortag option must already exist – agvtool will not create it for you.

And Hudson?

Hopefully it’s not too much of a stretch from here to see how we can use this in Hudson (or any other automated build system).  First off, we should create a project in Hudson that will check out our code and build it.  If you already have an existing Hudson project that builds periodically or with each new check-in you can simply clone it (Hudson is good that way).  Configure the project to only build manually by unchecking all the build triggers:

And add in new build step(s), calling agvtool to bump our build number and (if using SVN) tag the resulting build.  Note that if this project were set up to trigger a new build when check-ins are detected we have a potential race condition, with agvtool checking in changes which would trigger a new build which would make agvtool check in changes….

So, with these changes in place we can now reliably build a version of our code for testers, tag it and know that we can come back to the code for that build at any time.  And it’s all done automatically.  Also our version numbers will always increase, insuring that our testers don’t have trouble updating to a newer build.

And Another Thing

OK, I haven’t played with this one extensively yet, but will add it here for your consideration.  Hudson allows us to add parameters to a build.  When we start a build, it will ask us to supply parameters that affect the build.  As an example we can add a BuildNumber parameter that will decide which tagged version of our code we want.  Configuring it in Hudson will look something like this:

So what’s the use of this?  Well the parameter becomes an environment variable when Hudson is building the project.  So we can slip the environment variable into our source control link.  This way, when we kick off a build we can specify the tag to use, making it easy to recreate our App as it was at any stage in its development.

Well that’s it for this week.  If you have any questions or feedback please leave a comment below.

This post is part of iDevBlogADay, a group of indie iPhone development blogs featuring two 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!

Open a terminal window and cd to the build folder.  The online documentation says that you should unzip hudson and run it using the command:

java -jar hudson.war

This works fine on Windows, however under OS X, unzipping the file and trying to run it causes the following error:

If anyone can explain the issue, I’d appreciate the insight.  However it turns out we can just run Hudson as-is out of the zip file:

Ok, so what’s happened?  Hudson is now running as a Java application in the terminal.  As well as running the build, it also provides a web interface for us to work with.  Open a browser and point it at http://localhost:8080/ and you should see something like:

Before we set up our first job, we should grab a couple of handy plugins first.  Click on the Manage Hudson link on the left, then Manage Plugins and finally the Available tab.  You should see a long, slightly exciting (or intimidating, depending on your outlook on life) list of plugins.  Have a look through the list – there’s lots here to play with – but for now select the Twitter and Mercurial plugins (assuming I’ve convinced you to try Mercurial), and click on the Install button.

You should see the plugins being downloaded and installed, along with a message to restart Hudson.  When Hudson is running, there’s a Prepare for Shutdown option on the Manage Hudson page.  For now though, it’s enough to go to the Terminal window you’re running Hudson in and kill it with Ctrl+C (I’m a bit old fashioned that way).

Run Hudson again from the terminal window, and we’re ready to set up our first automated build.  For a start, let’s create a build that monitors our source control repository and kicks off a build when it sees any changes.

On the main Hudson dashboard, click New Job.  Give the job a name, choose the “free-style software project” option and click OK.

On the resulting page you can configure a bunch of options.  Feel free to go nuts here.  Each option has a ‘?’ icon that provides useful help.  Here’s the settings I used:

Under Source Code Management, I chose Mercurial and pointed it at my Fogbugz Repository.  The Fogbugz repository requires the user to be authenticated, so we do this by including the user name and password in the URL in the form:

https://USER_NAME:PASSWORD@PATH_TO_REPOSITORY

Note that, if your user name has a ‘@’ symbol in it, replace the ‘@’ with ‘%40′ to avoid the URL being incorrectly parsed by Hudson or Fogbugz (see the screen shot below).

Hudson also supports many other types of source control, pick the one that you use.  Another small note here – when setting up an automated build for the first time, it’s a good idea to use a small test project first, to allow faster testing of your set up.  My actual production code can take many minutes to build (not my fault! OpenFeint is slow to build), so instead, for this article, I’ve created AwesomeGame from one of the standard XCode templates.  Once I have a running build system, I’ll then go back and add in my production code.

Next up, we want to check if we need to trigger a build by polling SCM for changes.  We schedule Hudson to check SCM every minute using CRON-like syntax :

Then, we add the actual build step, executing a shell command to run XCode from the command line using xcodebuild.  Have a look at the xcodebuild man page for all the various options.  For now, we want to build our AwesomeGame target in both Debug and Release modes.  I’ve done this below using two build steps:

Finally, let’s tell Hudson how to notify us when the build is done.  I selected email and Twitter notifications.  If you’re on a team, notice the option to notify the individual who committed the changes that broke the build – without having to notify the entire team.  As well as the person responsible for the break it’s good practice to have a nominated ‘build monkey’ whose job it is to check all builds – so make sure they’re getting all the build results as well.   A quick note on Twitter here – don’t use your own Twitter account unless you want to spam all your followers!  Instead, create a bogus build account for Hudson to use, and follow it from your main account.

Assuming we’re all happy with the settings (we can always come back and tweak them), click Save.

Hudson now takes us to the page for our project.  On the left is a Build Now option – let’s try it out…  After a few seconds, you should see a progress bar in the bottom left, telling you that Hudson is building your project.  If nothing happens, check the top right of the page for an Enable auto-refresh option.

Once finished, we’ll see a blue ball that indicates a successful build (your code in source control does build, right?).  If instead you see a red icon, then the build has broken, and we need to fix something.  Either way, click on the most recent build link to see details of the build:

On this page, we can see the status of this particular build (remember blue ball means success), the changes in source control from the last build (none in this case, as we manually triggered the build) and the console output, where we can see the details of the code being checked out from source control and built using XCode.  If your build has failed, this is a good place to look for the problem.

Phew!  The system works!  Checking Twitter, sure enough there’s a success message there:

But hang on, where’s my email?  The problem here is that we need to configure Hudson with an smtp server so that it can deliver mail to us.  Go back to the Manage Hudson page, and click on Configure System.  Near the bottom you can configure the global settings for email and Twitter.  If you’re unsure what smtp server to use, check the settings for your email program – you’re looking for the name of your outgoing smtp server.

So enter in your smtp details, and the system admin email address (that’s you).  Click on the Test button and make sure that you get the test email message.

Going back to the main Hudson page, you should notice that our project is listed, and on the right hand side is a Build Now icon (so you don’t have to go into the project to kick off a build).  Click it to start another build, and then click on your project to follow the build’s progress…  Still no email.  Bugger.  Going to the project’s Configure screen, I look up the help for email, which sheds some light on the issue:

This is sensible – no point in spamming out emails when builds are all going well.

So by now we know that we can check out our code and build it automatically.  But where is the build?  Hudson creates a working folder in your root directory.  Have a look in ~/.hudson, and you’ll see all of Hudson’s internals.  In particular, the folder ~/.hudson/jobs/Awesome Game contains all of our build history and a workspace folder in which the code is checked out and built.  So if I want to get the built app, I can grab it from:

~/.hudson/jobs/Amazing%20Game/workspace/build/Release-iphoneos/

Later we’ll look at packaging up the build and putting it somewhere handy, but for now, let’s make sure that it’ll pick up on changes in source control.  Check out a working copy (if you don’t have one) of your project and put in a small change that will cause the build to break.  This ought to do it:

Commit the change (or commit and push if you’re using a remote Mercurial server like I am) and wait for a minute.  You may notice a message mentioning a ‘quiet period’ before the build kicks off properly.  This quiet period is Hudson waiting after it detects a change in source control to make sure all changes have been committed – this is particularly useful with CVS, where every file is committed separately.

Ah, BOOM!  Our build has failed nicely.  And I got an email this time, which is nice  A broken build is  something that shouldn’t be left broken, so let’s fix it and check the build comes back happily.  Fix the code, push, commit, wait… success!  Twitter and email confirm everything’s OK.

We’ve covered quite a bit so far so it’s probably a good time to take a break and see what we’ve achieved, and how that matches our goals from last week.

What works?

• Monitor source control (Mercurial and Subversion in my case), kicking off a build whenever changes are checked in.
• We’ll be able to manually kick off a build as needed.
• The build will grab all our source code from source control and build it in all relevant configurations – debug, release, simulator, device and so on.
• When the build is finished, it’ll notify people of the success / failure.
• There’ll be a handy location (web page most likely) where we can monitor / control the whole thing.

What do we still need to do?

• We’ll schedule a nightly build as well, just in case anything outside of source control has changed. This is fairly simple – an exercise for the reader!
• Copy a successfully built app to somewhere useful, preferably packaging it up with a provisioning profile in a zip archive, ready for emailing.
• Automatically update version numbers on our ‘stable’ build with each build.
• Bundle up the resulting builds with a provisioning profile and copy them to a shared folder.
• Start up automatically under when your build machine is booted.
• Paint a unicorn.

OK, plenty to work on, I’ll be back next week with some more detail, or if you’re keen have a crack yourself and let me know how you get on!

Disclaimer: I’ll let you in on a secret now, to avoid disappointment later on.  By the end of this article you won’t have a fully working automated build  The reason is that I was half way through writing up this article using CruiseControl

What?  Why?

An automated build is a system that can build your software from source to finished product without human intervention.  At it’s simplest, this can be an XCode project or a makefile – after all, you don’t compile each file and link them together by hand, do you?  The key idea is that we can remove human error from the process, making it more efficient.  The ideal is to have a system whereby you can build all versions of your software with a single click (and also score a couple of points on the Joel test).

Consider the following situation.  You want a fresh build of the code to show off to your boss, “Reckless” Jim, to keep him off your back.  When you wake up, you grab your iPhone 4 (lucky bastard), open Safari and click a link on a web page before you get in the shower (remember to put the iPhone down first).  While you’re halfway through your hot water supply (and the Sound of Music soundtrack), the following is happening:

Cool, huh?

Or how about this:

Neat, eh?

This second example is what’s known as continuous integration – every time you check in new code to source control, the whole build is exercised to make sure nothing’s broken.  Why?  Often a broken build is a simple 30 second fix at the time, but 2 weeks later it might require hours of sorting through commit logs to see where the problem is.

The solution

So, what does it take to set up a system like this?  Not as much as you might think.  There are some neat tools out there to get you up and running fairly quickly.  The problem is that I didn’t have time to try out both of the likely candidates for this week’s deadline.  I’ve used CruiseControl before, and Hudson looks promising.

So here’s the goal for next week.  I’ll show you how to set up a system that will:

In the mean time here’s a couple of sample chapters from Pragmatic Project Automation: How to Build, Deploy, and Monitor Java Applications that covers the basics of setting up CruiseControl.

So, now to decide between Hudson and CruiseControl.  If you have any thoughts on either of these systems (or another I haven’t heard of), please let me know in the comments below…

Any good software developer is always on the look out for new techniques or tools. But when was the last time you actively cultivated your social skills?

Does this sound unecessary? We’re coders after all, dealing with syntax and pixels, right? Well consider this. Our games are nothing until we’ve put them into the hands of our players. It’s a social contract we have with the players to offer them a fun and engaging experience.  And most importantly, if they don’t like it, you’re up the proverbial creek without a paddle.

If we’re going to make our game great, we need to see it’s effect on potential players. For the best results, we need to do it early and often to avoid wasting time on ideas and implementations that just aren’t good.

So, assuming you’re buying into this argument so far, the next step is to get some feedback from players. Giving and receiving feedback is very difficult to do well, and it’s a skill that continually needs to be trained and refined, alongside your other mad skillz.

Giving feedback

Giving feedback can be difficult – you need to let the game developer know what doesn’t work, but without leaving them whimpering in a corner when you’re done. The trick here is to think of a hamburger’s fluffy buns. The idea is that you wrap the “meat” of your concerns in between a nice couple of “fluffy” buns to soften the blow.

Example:
“Your game crashes all the time and is unplayable.”

Example:
” I like what you’ve done with the art style, and I can see a lot of promise in your game Mega Zombie Ninja Defense HD. However, I’m having trouble with the game quitting unexpectedly on me. It happens fairly regularly at the start of each level and is making it difficult to get into the game. I’m keen to get further into the game, please let me know if I can help in tracking down the problem.”

So, both of these comments say basically the same thing right? But which would you rather receive from a beta-tester? Here’s a few key points:

• The first example comes across as a personal attack on the developer, mainly through the use of the word “Your”. It’s the written equivalent of stabbing your finger at someone to make a point. The recipient of this comment immediately becomes defensive and unwilling to take on board your comments.
• Also in the first example, the phrases “all the time” and “is unplayable” are absolute (rather than subjective) statements about the game that may not be true. “Crashes all the time for me“ may be true, but can you really speak for all the other testers playing the game?
• In the second example, the initial compliment puts the developer in a receptive frame of mind, ready to listen to your concerns – establishing a dialogue. Talking about “the” game rather than “your” game makes for an objective discussion, rather than an emotional one.
• Expressing the problem in terms of “my experience” means you’re open to the possibility that it’s not the developer’s fault – perhaps you’ve updated to a new OS reveision that they haven’t had a chance to test yet, or perhaps you’re jailbroken phone running a Linux kernel may have something to do with the issues you’re having.
• You’ve knocked the guy down and given him a kick in the guts, telling him his code crashes (even if it’s true, it’s not nice to hear), so wrap up by saying something nice to pick him up off the ground again feeling positive about what needs to be done.

There’s more at stake here than just being all new age and caring. It’s about being able to get to the heart of a problem and fixing it. The fact that it can help build a stronger relationship with someone is just a nice side effect.

It is better to give than to receive

OK, so let’s say your the king of fluffy bins, and people love you as a beta tester because you give honest, helpful feedback. Now it’s your turn to send a build out to a handful of testers.  It’s hard.  You’re feeling a bit nervous – hoping they love the game, terrified that they won’t. And then you get this:

“Man this sucks, couldn’t you do any better?”

Ouch. What can you do? First off, try not to take it personally. You asked for peoples opinions, you have to be prepared to take the good with the bad. If people only offer praise, you’re game will suffer for it. Just watch American Idol some time if you don’t believe me. All those poor people who can’t sing to save themselves.  I can just imagine their well meaning family telling them “You’re fantastic, you can do anything you want to do”.

OK, so we’ve gotten over the initial shock of the feedback. Now it’s time to ask yourselves “Why did this person have such a bad experience?” There’s obviously a problem here, and you need to develop the skill to find out what’s going on. This is where the “Five Whys” technique comes into play. Let’s imagine how the conversation could go:

“Man this sucks, couldn’t you do any better?”

“Wow, I’m sorry it didn’t go so well for you, can you give me an idea of what went wrong?”

“I just couldn’t get into it.”

“Why was that, was it too hard? Did the controls make sense?”

“It was OK until I reached the first platform, I just couldn’t get up onto it.”

“Why was that, were you double jumping?”

“Double jumping? You can do that?”

“Yeah, just triple tap the player again after he’s jumped. Did you read the instructions at the beginning of the game?”

“Oh those, I kinda skipped through the last seven pages.”

“Fair enough, maybe I should look at shortening them down a bit. Triple tap may be a bit tricky too, I guess I could look at using a tap and hold or something. That shouldn’t take too long to fix. If I sent you a new build, would you give it another go?”

“Sure, sounds good”

Wonderful, a happy ending. With a little effort on our part, we’ve turned a flippant, unhelpful response into some valuable information:

• If a player can’t master double jumping, the game is unplayable.  Is it really that important a skill for our game?
• Triple tapping is a pain.
• Our “how to play” instructions are too long.
• Maybe we should put the first time the player is required to double jump further into the first level?
• Perhaps we can shorten the instructions and break them up into smaller chunks, delivered as needed rather than all at once?

All that from “Man this sucks, couldn’t you do any better?” . The idea of “five whys” is to strip away the superfluous and get at the heart of a problem.

Wrapping up

A bullet list to wrap up:

• Avoid being personal (using “you”), unless you’re talking about yourself (“I think”).
• Think of it as a puzzle to solve objectively.  The answer is there, you just need to develop the techniques to find it.
• “Never attribute to malice that which is adequately explained by stupidity.” A person who’s gone to the effort of offering criticism may have a valid problem they don’t know how to communicate.
• Your harshest criticism is also you’re greatest opportunity for improvement.
• Be wary of feedback from friends and family – avoid asking what they think – rather ask them for ways to help you improve and fix the game.

So, maybe there is something to being nice after all. Mastering the art of giving and receiving feedback may seem unimportant at first, but it’s one of the most valueable tools you have.

What do you think?

A Commitment

Which brings us to today…

Faerie

So, let me introduce Faerie (a working title).  It’s still in the very early stages of development, but it’s had encouraging feedback so far from people who have seen it.

Goals

Theme

Art Style

Mechanics

Faerie began as a desire to make a game that my kids could play that still felt challenging to play as an adult.  Combining Bejewelled style scoring with geoSpark (App Store link) style action was the plan, although I’m happy to say the resulting mechanic is quite different now – including elements from Tetris, Whack-a-mole and Bejewelled.  This is perhaps the most sensitive area for me, so I’ll leave it at that.

So when’s it ready?

So, not quite the ‘Full’ Monty, but now you know what I’m working on, please bug me to get it done before my kids grow up!

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

Obtaining a Fix

The Pragmatic guys frequently run special promotions, and it’s quite common to get up to 50% off many titles.  In particular if you sign up and then recommend a friend to sign up, you’ll both immediately get 40% off coupons to redeem on any purchase.  If you don’t have any friends who are sufficiently book-nerdy like you and me, drop me a line at george.sealy ‘at’ gmail.com and I’ll send you an invite so we can both enjoy a discount

Some Great Books

The Art of Game Design : A Book of Lenses

Beginning iPhone 3 Development: Exploring the iPhone SDK

User Interface Design for Programmers

Game Engine Architecture

The Pragmatic Programmer: From Journeyman to Master

My Name is George

There have been a lot of people talking up Distributed Version Control Systems (DVCS). Until recently, I’d assumed that it was the same people who have been talking up Linux for the last 15+ years. Don’t get me started on them. It seemed the principal argument used by many people was ‘everyone has their own repository’. To me, that sounded like a recipe for disaster – I’m far happier with the concept of a central, authoritative repository.

So I was surprised when Joel Spolsky came out in favour of Mercurial (or Hg), a DVCS. Joel’s a fairly level headed, mainstream kind of person – what was he doing fraternizing with the Linux-loving hippies and beatniks? After reading his Hg introduction, I realized I was in danger of becoming a convert too. When you’re done here, you may want to go over to hginit.com – you won’t find a better introduction to Hg or distributed version control in general.

What’s so good about it?

So, it turns out that DVCS is a viable alternative to regular, vanilla flavored version control. And by that I mean Subversion or CVS, the systems I’m most familiar with. There’s a few main points that convinced me to give Hg a try:

• It’s not too dissimilar to ‘normal’ source control, meaning it’s fairly simple to make the transition (add files, update, commit, revert etc work basically the same way)
• Rather than worrying about ‘everyone’ having a repository, the key thing is that you have your own local repository that’s just for you. So you get the safety net of frequent check-ins without having to worry about ‘breaking the build’.
• Branching is something a lot of people strenuously avoid with Subversion, because the tools just aren’t set up to handle it easily. Because of the way Hg tracks changes, merging branches is a simpler and more reliable process.
• Mercurial still supports the idea of a central repository, and in fact handles multiple staging servers (development, stable, release etc) fairly well.

I’ve been using Hg on a couple of projects for a while now, and I like it. The big wins for me are how simple it is to set up a new repository and how convenient it is to have a local repository for frequent check-ins.

Getting started

So what’s needed to get started? Well the good news is that all the tools you need are freely available and well made. First off, you really should read Joel’s introduction. After that, the command line tools are available from here. Using the command line is a great way to learn a version control system and really understand what’s going on – and it’s surprisingly simple.

Sooner or later though, you’ll want to look at some sort of GUI though to speed the process up. @bunnyhero put me onto MacHg which I’ve been using for a week or so now it’s been excellent. There’s a good screencast that covers the basic features of MacHg and will get you up and running straight away.

You may think that not having your version control inside XCode is a pain, but in fact I think it’s a huge bonus to separate IDE and version control. I’ve never seen source control handled properly inside an IDE (I’m thinking Visual Studio, Eclipse and XCode here). Version control is about files and folders, and I don’t want the IDE thinking it know better than me how to apply version control to a project by making ‘assumptions’ to try and streamline the process.

And finally, one of the strengths of version control is that it forces you to maintain backups of your code base. And the best backup is an off site one. Setting this up is a pain, right? Actually no, as once again Joel comes to the party and makes this easy. His company Fogcreek offer remotely hosted project management, bug tracking and version control tools, including support for Hg (they call their Hg toolset Kiln).

Obviously this is service you pay for, right?  Yes.  Unless you are a student or small company (or in fact anyone who doesn’t need more than two active users), in which case it’s FREE. Setup is trivial, and before you know it you can have a professional grade offsite Hg server of your very own.

While you’re at it, you also get their Fogbugz tools as well, so simple bug tracking, scheduling, wiki, code review and customer support all come as part of the free package. Nice. I should point out I get nothing for recommending Fogcreek, I’m just a bit of a fanboy.

Give it a go

So there you are, if you’re looking for an easy way to get into source control, or you’re sick of merging branches in Subversion, you might give Hg a go. All the tools you need are freely available for a small scale team and the learning curve is not that steep.

One last detail – I did have a little trouble getting MacHg to talk to Kiln . The problem is that MacHg needs the URL to include your username and the repository URL, and separates them with an ‘@’ symbol. Kiln’s user names are typically your email address , so MacHg get’s a little confused when it sees something like:

https://george.sealy@gmail.com@acornheroes.kilnhg.com/Repo/Repositories/Group/FaerieDev

Fortunately, the solution is fairly straight forward, you can ‘escape’ the ‘@’ symbol in your user name like so:

https://george.sealy%40gmail.com@acornheroes.kilnhg.com/Repo/Repositories/Group/FaerieDev

Needless to say I jumped on this idea to aid in tuning my current game prototype. I’ve just reached the stage where rapid tweaking of variables is going to help focus and refine the game play. Miguel suggests hooking a Lua scripting engine into your code, but I thought it would be fun to create my own, plus most of my code is C++ (rather than Objective-C) and I’ve found binding Lua to C++ to be a fiddly process in the past.

The corresponding code for this article can be found here. Note that the DebugServer code comes from Miguel’s article, and the AsyncSocket code comes from here.   I’ve added a minimal amount to Miguel’s code to pass received commands on to the DebugUtils functions found in Debug.[h|mm]. I haven’t had time to create a complete sample project, but the code provided should drop into any existing code base with minimal fuss. If the coding style looks a little strange, you may want to also read this and this.

So, let’s start at the end and work backwards, which I often find to be an effective technique. When tuning a game we spend a lot of time tweaking variables and constants – maximum speed, rate of fire, gravity, item prices, animation durations etc. Wouldn’t it be nice to open up a telnet session to your App and enter a command like “gravity = -8”? Alternatively, maybe there’s a set pattern of enemies that causes a rare bug. Wouldn’t it be nice to enter a “SetupWeirdEnemyPattern” command for easy testing?

So, we have two common scenarios – tweaking a variable and executing a function that alters the game state in a slightly more involved way. The code below allows us to do this. Variables and functions can be “registered” and given a name, which we can then use to adjust values or execute functions via our telnet connection. To make it simple to pass in parameters to these functions, we pass in a set of text parameters using argc and argv, just like the main() function of a C++ program.

Let’s have a look at the public interface to this code:

typedef bool (*DebugCommandFunc)(int argc, char *argv[]);

namespace DebugUtils
{
    void Initialise();

    bool ProcessCommand(const char *command);

    bool RegisterCommand(const char *commandName, DebugCommandFunc commandFunc);

    bool RegisterVariable(const char *variableName, bool *var);
    bool RegisterVariable(const char *variableName, int *var);
    bool RegisterVariable(const char *variableName, float *var);
}

Not much there, is there? The guts of it is in the ProcessCommand() function, where we pass in a string, and magic happens. Or, to provide an example:

bool ResetGameCommand(int argc, char *argv[])
{
// Do stuff here to reset the game state
}

DebugUtils::RegisterCommand(“ResetGame”, ResetGameCommand);

And later, through a telnet connection, we enter “ResetGame”, which in turn calls:

DebugUtils::ProcessCommand(“ResetGame”);

And, just like magic, we reset the game state.

Or as another example, we could register a game variable, say…

DebugUtils::RegisterVariable(“gold”, &gameState.pileOfDubloons);

And then, through the telnet connection, we can tweak this value mid-game, by entering:

“gold = 10000”, or “gold *= 2.0”

I’ve intentionally kept this system as simple as possible, but there’s a lot of power here. It’s very simple to register variables or add short pieces of code that can be run as needed. Just a few examples – turning on debug drawing to see bounding boxes of physics objects, changing the value of gravity or a jump pack’s thrust, loading an arbitrary level, turning off collision detection – the sky’s the limit.

The key thing here is to let you spend as much time as possible refining and tuning your game, because as Jesse Schell describes in his excellent book The Art of Game Design: A book of lenses:

The Rule of the Loop: The more times you test and improve your design, the better your game will be.

In other words, by removing the code-compile-run stage from tuning our game, we can create a better game in less time. Hopefully this code, combined with Miguel’s will provide a simple way to help you refine and debug your game.  Happy tuning!

P.S. I was planning to include a description of how I used TDD (Test Driven Development), but figured this post was long enough. If it’s something you’re interested in though, leave a comment or drop me a note on Twitter (@GeorgeSealy) and I’ll put together an article.

P.P.S. Yes, there’s a few things that could be added to this code to make it even more useful. At the moment it’s not possible to pass a parameter that’s a string with spaces or new lines in it. To do this, you just extend the tokenizing code to respect quoted parameters like “This is a string”.

P.P.S. I’ve resisted the temptation to allow more complex calculations such as “percentComplete = 100 * itemsFound / totalItems”. Most of the time all you want to do is tweak values. If you need this much power, hook in Lua as Miguel suggests, don’t roll your own as it becomes increasingly difficult to maintain as a project matures.

P.P.P.S. I’ve also just realised one of the more useful things I’ve left out – if you just supply the name of a variable on its own, then the variable’s value should be either returned via telnet or printed out using NSLog or similar.  There’s nothing worse than finding the perfect value for something and then being unable to see what it is!

P.P.P.P.S. The observant amongst you may have noticed that the link to Jesse Schell’s book is an Amazon Affiliate link, meaning if you follow that link and subsequently purchase something I may get a small commission. I will only ever put such links to books that I have bought myself or at least read cover to cover and would recommend.