Redesigning text adventures for iPhone and Android

5 December 2011
This post was originally published on Gamasutra.

"The Things That Go Bump In The Night" is the first text adventure game specifically designed for smartphones, and is now available in both the App Store for iOS and the Android Market.

It's the first app that has been created from a game written for the Quest text adventure system, which I have been developing for a number of years now. The game was written by Tim Hamilton, and in it you play a security guard settling down to a quiet night shift, when things start to go wrong. You must make your way around the compound, solving puzzles and dispatching mysterious beasts.

I believe it is the first text adventure to be specifically designed for a pocket-sized touch screen - unlike old text adventure games which rely heavily on keyboard input, you can play this game entirely without typing. Instead, you use hyperlinks and tabs to navigate and interact with the game world.

I've written here before about the time being right to bring back text adventures by making them easier to play and embedding them on websites, so the obvious next step was to bring them to smartphones too. I think this kind of game can work well as a casual game, as you can just pull a text adventure out of your pocket and play for as long as you like, and you don't need sharp reflexes or great co-ordination - great for playing on public transport!

The way the app works is by using a tool which I've built to convert Quest games into pure Javascript. Using Phonegap, this HTML/JS is then wrapped into a cross-platform app. On iPhone, the NativeControls plugin is used to display native tabs at the bottom of the screen, and to bring up native menus. On Android, it was simple to code a "tab" switcher via the Menu button, and game menus themselves are displayed using a jQuery UI dialog.

Two Conversions
The first step in bringing the game to smartphones was to convert Tim's original game to the latest version of Quest. Tim Hamilton originally wrote "The Things That Go Bump In The Night" using Quest 4, which is effectively a completely different system to Quest 5, as that was a total rewrite (although it does share some of the same design ideas). So the first thing to do was convert a Quest 4 game into a Quest 5 game. I wrote a converter application which converts most of a game correctly, although there were still a few manual tweaks to do - even some Quest 4 bugs to emulate! What really helped was to have a complete walkthrough for the game - Quest 4 has a "transcript" feature which is similar to Quest 5's walkthrough feature. This meant I could have Quest 4 and 5 automatically play the game through to completion, and compare the output, fixing things as I went along.

I then sent Tim the converted Quest 5 game, and he made a few more tweaks and corrections. He also adapted the game to make better use of hyperlinks. Tim's enhancements made it possible to play the game through in its entirety, without the player having to type anything.

Re-engineering Quest
The next step was to convert Tim's enhanced Quest 5 version of the game to Javascript, using a converter which I had started developing a few months ago. I'd thought the converter was 90% done, but as is the case with so much in the software world, the last 10% took far longer than the first 90%. The main difficulty has been threading. Javascript is single-threaded, which means you can't pause a running thread while you wait for some user input. This meant I needed to re-work all of Quest's functions for displaying menus, waiting for keypresses, asking questions etc., and as a result had to refactor some fairly fundamental code such as the parser. Eventually I had a pure HTML/JS version of the game which could be played in any web browser. I implemented the walkthrough feature to verify the game was working correctly, and again I sent it to Tim so he could check for any "off-walkthrough" problems.

Now the game was working in HTML/JS, it was straightforward to wrap it in Phonegap and create a functioning app. Even here there were unexpected problems - although the app ran at a respectable speed on my iPhone 4, when I ran it on my old iPhone 3G I was horrified to find that it would sometimes take 10 seconds to respond to a command. The fix was again some re-engineering to improve performance.

The desktop/web version of Quest 5 saves games by writing out the entire game state. The JS app version takes a different approach, saving a delta instead - only changed attributes are saved to local storage. This is quicker, requires much less local storage, and also means that the app can be safely updated without breaking existing games. The delta is automatically saved after each turn. Again I found some performance issues here, so it took a bit of time to get this right. With a Phonegap app on the iPhone, you get no warning if your app is going to be terminated, so I had to make saving robust enough that it wouldn't break things horribly if the game started saving but never finished (instead, there are effectively two save slots that are used alternately, so the worst that can happen is you lose one turn).

By now I had the game working pretty well on iOS, and sent it to a few beta testers using TestFlight, which I highly recommend as it takes much of the pain out of ad-hoc distribution on the iPhone. I thought it would be a good idea to get it working on Android too, and I was pretty pleased when only two days after I took delivery of the cheap but surprisingly capable Samsung Galaxy Ace, I had a version that worked on that too.

I was pleased with the overall Android development experience - it seems so much more developer-friendly than iOS. The documentation is laid out in a way that a mortal can understand, and it's so much easier to send a build to beta testers - just email an APK file. Much more pleasant than dealing with certificates and distribution profiles on iOS.

Available Now
It took about a week for my app to be reviewed by Apple, so today finally the game is released on the App Store and is also now available on the Android Market.

Feedback from the beta testers has been pretty positive - but it is a pretty difficult game, so should keep you occupied for a while!