Hack 36. Play Zork on Your BlackBerry

With this Java-based mini Infocom interpreter, you can play retro text adventures on your BlackBerry. You can even write your own games if you want!

"Open mailbox. Take leaflet and read it." Those are the sentences you need to kick off a game of Zork, which is, to many, the prototypical text adventure. You're more likely to hear these games referred to as interactive fiction these days, and although many things have changed since the days when Infocom and Adventure International owned the genre, these games are very much alive.

You'll find a thriving community of interactive fiction gamers and authors at the Interactive Fiction Archive (http://www.ifarchive.org/). On this site, you'll find hundreds of games, tools to create your own, and all sorts of information.

As a text-friendly handheld, the BlackBerry is the perfect platform for interactive fiction. There are a couple of ways you can play these games on your BlackBerry. Z2ME (http://gpf.dcemu.co.uk/) is a port of ZPlet (http://sourceforge.net/projects/zplet/), a Java-based interpreter for the Z-Machine, the virtual machine that Infocom used for their interactive fiction games (compiled games are said to be in the Z-code format and have a file extension indicating which version they were compiled for, such as .z3, .z5, and so on). Many modern interactive fiction titles use the Z-Machine, so you'll find plenty of games for it. Another J2ME Z-Machine interpreter is ZeeME (http://www.gizmo-a-gogo.org/ZeeME/index.html).

Both Z2ME and ZeeME will run fine on the BlackBerry, but there is a customized version of Z2ME that is more BlackBerry friendly. However, I was unable to get it to work on the 7100 series of BlackBerry handhelds, since Z2ME did not work correctly with the SureType input methods.

3.6.1. Find Games to Play

One of the problems with both Z2ME and ZeeME is that they come with one game (Mini-Zork). To add another game, you'll need to modify the jar file and install it on your device.

Because there is a limit on the size of a jar file (the biggest jar I've been able to load is 76K), you need to pick small games. To see a directory listing of all the Z-code games in the interactive fiction library, visit ftp://ifarchive.org/if-archive/games/zcode/. If you open that URL up in a filesystem viewer, such as the Mac OS X Finder or Windows Explorer, you'll be able to sort by file size. Look for small Z-code files, and cross-reference what you find with the listings at Baf's Guide to the Interactive Fiction Archive: visit http://www.wurb.com/if/platform, scroll down to "Z-code," and click the link. Then you can look up a game you're interested in and read a synopsis and review. Not all games are listed, but Baf's is authoritative enough that you safely use the absence of a review as a filter. If you've got all the time in the world, though, you should try everything. There are worse things you could do with your time.

For example, suppose 905.z5 catches your eye. It's 60.5K and might be small enough. So you head on over to Baf's, locate a review, and see that it got a decent review (four stars). Then you download the file, and use the instructions listed in the next sections to package it. Next, create a .jar (or .alx), post it on a web site for an OTA download (or use the Application Loader) [Hack #97], and start playing the game on your BlackBerry.

If you do want to post .jad and .jar files on your own web site, make sure you have the proper MIME types set up [Hack #97].

3.6.2. Use Z2ME

Z2ME is available from http://gpf.dcemu.co.uk/ as an over-the-air installation (OTA). There are also Application Loader versions available if you have problems with the OTA install (see Phillip Bogle's post at http://www.thebogles.com/blog/2005/06/play-infocom-classics-on-your.html if you are determined to do an OTA install). When you launch Z2ME, Mini-Zork will appear. Figure 3-18 shows an intrepid adventurer doing something very wise.

Figure 3-18. No one wants to be eaten by a grue

Although Mini-Zork will keep you busy for a while, you might want to play some other games. It takes a bit of effort to set this up (and it's lot easier with ZeeME), but it's well worth it. Unfortunately, Z2ME only supports Inform Version 3, and you may not be able to find many compiled games in that format (Versions 5 and higher are more common). But if you search the archive (and Baf's guide), you'll find some.

Suppose you download dejavu.z3 from the Interactive Fiction archive. You now need to rebuild the Z2ME jar file to hold this new game.

You'll need to grab the source code to the BlackBerry version of Z2ME from http://gpf.dcemu.co.uk/ and open it in the BlackBerry JDE. Remove minizork.z3 from the project and replace it with dejavu.z3. Then, find the blackberryZ2ME.jad file in the project and change the Zfile: entry from:

 Zfile: minizork.z3 

to:

 Zfile: dejavu.z3 

Save and compile the project, and you'll have a jar that contains a different game.

3.6.3. ZeeME

ZeeME's user interface is a bit rougher than Z2ME's, but it supports newer Z-code files, and also has a nifty packager that lets you easily create jars of games. To use ZeeME on a BlackBerry, scroll all the way to the bottom of the screen, type your command in, and click the trackwheel to bring up the menu. Click Input, as shown in Figure 3-19, to enter your command. Be sure to use the Settings menu to set a comfortable screen width as well.

You can download ZeeMe at http://www.gizmo-a-gogo.org/ZeeME/index.html. Both the .jar and .jad files are included on the site. Since the jar's MANIFEST contains everything ZeeME needs to know to function, you can install directly from the .jar rather than from the .jad.

As with Z2ME, ZeeME includes Mini-Zork. If you want to run additional games, you'll need to create a separate .jar file for each of them. Also available on the ZeeME web site is the ZeeME Packager, which is a simple application you can use to create ZeeME jars (you should be able to double-click on the packager .jar file to run it). Simply specify the Z-code file, the game name, and the name of the jar you want to create, as shown in Figure 3-20.

Figure 3-19. ZeeME's minimalist user interface

Figure 3-20. Packaging up 905

Post this .jar online for an OTA download (as described in "Find Games to Play"), or use the Application Loader to install it. If you need to create a .jad for it, it's pretty easy. Use jar tvf jarfile (for example, jar tvf 905.jar) to find out the name of the Z-code file (for example, zeeme/games/905.z5) and its size. You'll also need to know the size of the .jar itself.

Set up the .jad as follows:

 GameTitle0: 9:05 MIDlet-Jar-Size: 73066 GameFile0: /zeeme/games/905.z5 MIDlet-1: Minizork,,zmachine.ui.ZeeMEMidlet MIDlet-Jar-URL: 905.jar MIDlet-Version: 0.1.0 MIDlet-Name: 9:05 MIDlet-Vendor: Craig Setera GameLength0: 61952 

You can also peek in the jar's META-INF/MANIFEST.MF file to get the needed values.

3.6.4. Hack the Hack

It's amazingly easy to make your own game. Graham Nelson's Inform (http://www.inform-fiction.org/) will let you create Z-code games. Here's the code for a simple game where you are trapped in a lousy place until you can get your BlackBerry working again:

 Constant Story "My BlackBerry"; Constant Headline   "^ A simple amusement^"; Include "Parser"; Include "VerbLib"; Include "Grammar"; Object battery "battery"   with description "A Battery",   name "battery",   before [; Insert:   if (second == blackberry && blackberry has open) {    deadflag = 2; ! indicates you've won the game   }   ],   has concealed; Object blackberry "BlackBerry"   with name "blackberry", article "your",   description [;     if (self has open) {   "This is a BlackBerry 7100t; it's missing a battery."; } else {   "This is a BlackBerry 7100t"; }   ],   before [;     Open: if (self hasnt open) {   give self open;   "You notice that the battery compartment is empty!"; } else {   "That's already open."; }   ],  has container openable; Object Startroom "Street"   with description "This is a dark and damp street, and it doesn't feel safe.  You're standing under the only streetlamp you can see  for blocks. If you called someone, they'd come and  pick you up.",   n_to "That way doesn't feel safe.",   s_to "Maybe if it wasn't so dark to the south.",   w_to "It's dark that way, and you hear hungry squishing sounds.",   e_to "You feel safer under the lamp.",   has light; Object rock "rock" Startroom   with description "This is a damp and yucky rock.",   name "rock",   before [;   LookUnder:    if (battery has concealed) { ! It's concealed until we find it   move battery to player;   give battery ~ concealed;   "You found a battery!";    } else {      "There's nothing else under the rock.";    }   ]; [ Initialise;   location = Startroom;   move blackberry to player;   "^^^BlackBerry Adventure^"; ]; 

Download an Inform compiler and the libraries (a bunch of .h files) and copy them into the same directory. At the time of this writing, the latest Inform compiler (6.3) was creating Z-code files that were too large to create a reasonably sized .jar, so I suggest that you grab a Version 5 compiler and libraries from http://www.ifarchive.org/indexes/if-archiveXinfocomXcompilersXinform5.html.

Save the code into a file in the same directory, and call it bbgame.inf. When you look at the contents of your working directory, if you see these files, you know you're good to go (if you're on Unix, Linux, or Mac OS X, Inform won't have an .exe extension):

bbgame.inf

grammar.h

inform.exe

parser.h

verblib.h

Compile bbgame.inf to a .z5 file with:

 inform bbgame.inf bbgame.z5 

You should now have a file called bbgame.z5. Use the instructions from the previous sections to package it up in a .jar file, and play it on your BlackBerry. For more information about hacking your own interactive fiction games, see http://www.inform-fiction.org/index.html.

Brian Jepson