A2Z Machine: Running Zork on an Adafruit ItsyBitsy M4 Express

Note: This blog post has been updated for version 3.2 of the A2Z Machine

When the interactive fiction game of Zork first appeared on home computers in the 80’s, it was truly magical. Users playing the game were able to type sentences like “open mailbox and read leaflet” and the computer would understand it. The parsing engine was truly a technological feat for 8 bit computers at the time, some of which had only 48KB of memory. Also, there was no “cloud” where the sentences were uploaded to a cloud service for analysis like Amazon’s Alexa and Google Home, analysis was all done locally. The end result was a rich game environment that provided hours of entertainment. Sadly, the popularity of Zork and other interactive fiction games declined as home computers became more powerful and games with computer graphics emerged. Fortunately, Zork still lives through ports to new environments like the A2Z Machine.

Zork was originally developed in the late 1970’s on a DEC PDP-10 computer at MIT using a descendant of the LISP language. There was also a FORTRAN version that was translated to the C language. When the development moved to a commercial endeavor through the startup company Infocom, Zork was rewritten in two parts: An interpreter and a story file read by the interpreter. This allowed Zork to run on many different computers, where there were quite a few in the 80’s. The same story file could be used on any computer, only the story interpreter had to be created for that computer. This also allowed new stories and sequels to be created that could run using the same interpreter. The name for the interpreter was called the Z Machine. There are several open source Z Machine implementations available. My goal was to implement a Z Machine on an Arduino compatible microcontroller that allows playing Zork and other compatible interactive fiction games.

The requirements to run a Z Machine are straighforward:

• A processor that can compile/run C programs
• Enough RAM to hold the Z Machine and story file
• Storage to store one or more story files and associated save files
• Keyboard and terminal support

Fortunately, the Arduino IDE is based on the C++ language, a language which has its roots from the C language. At least one attempt has been made in the past to port Zork to Arduino (See Zorkduino) . However, past Arduino implementations had to deal with one or more limiting factors of these requirements. For example, not enough memory was available to hold both the story file and Z Machine, or an SD Card had to be added for the story and save files.

I was looking to match most if not all the Z Machine requirements using a modern day Arduino compatible device. What I found was one of the smallest ones around: the Adafruit ItsyBitsy M4 Express. This device measures only 1.4″ by .7″ (35.9mm x 17.8mm) and can fit in the palm of your hand. Considering the size of the original DEC PDP-10 used for the first Zork version, you have come a long way, baby!

The ItsyBitsy M4 Express matches all the requirements to run the Z Machine “out of the box” (even though it comes in a plastic bag):

• ATSAMD51 32-bit Cortex M4 Processor using the Arduino IDE
• 512 KB flash for the Z Machine, 192 KB RAM for loading the story file into memory
• 2 MB SPI FLASH chip for storing story files and save files
• Serial interface for keyboard and terminal

The original Zork story file is about 90KB in size, which leaves plenty of room in the M4’s 192 KB of RAM for the Z Machine. The 2MB SPI FLASH provides enough storage for plenty of Z Machine games and save files. Adafruit has another ItsyBitsy Express version utilizing the ATSAMD21G18 M0 chip, however its 32KB of RAM is not large enough to load the story file into memory using the default implementation of the A2Z Machine. There may be a way to get it to work on an M0 chip through rewriting the caching mechanism, but I decided to spend a few more dollars and save myself hours of research and coding. Adafruit also offers the larger Feather M4 Express that should work since it has similar features, but I have not tested it. In fact, any future “Express” Adafruit products featuring the M4 chip should work since they should contain similar requirements needed for Circuit Python.

The ItsyBitsy supports serial input and output from its UART support using the USB port. So you can use your favorite terminal emulator to play Zork. I used PuTTY for Windows (yes it is not just for ssh and telnet).

The code for this project originated with the JZip 2.1 project at SourceForge.net.

Here is a list of features of the A2Z Machine:

• Play interactive fiction games based on the Z Machine
• Retro themes available
• Unix-like ncurses support
• Save and restore games using the Quetzal file format (platform independent format supports files saved from other platforms)
• No additional hardware or soldering needed when using the ItsyBitsy M4
• Uses the default settings of PuTTY

Installing the Story Files

The Zork trilogy game files are included in the games folder of the A2Z Machine GitHub project. First create 2 folders in the ItsyBitsy file system: “stories” and “saves” . Then copy the files from the games folder in the GitHub project to the stories folder on the ItsyBitsy. The “saves” folder will initially be empty but will be used later for storing and retrieving saved games. The A2Z Machine supports Z Machine files version 3 and version 5 (usually “.z3” and “.z5” extensions). You can find other compatible games and resources on the internet, including these sites:

The Interactive Fiction Archive
The Interactive Fiction Database
Z-Machine Matter

When uploading a sketch to the ItsyBitsy, CIrcuit Python will be removed and the filesystem on the ItsyBitsy will not be available for managing story files. Instructions on restoring Circuit Python can be found here. Note: the comment “You only have to install CircuitPython ONCE …” does not apply here. You will need to re-install CircuitPython after you upload the A2Z Machine sketch whenever you need to add or delete games or save files on the file system. You will then need to compile/upload the sketch again (see next section).

Beginning with version 2, the A2Z Machine utilizes the TinyUSB library, which allows for drag and drop of Z Machine game files without having to reinstall CircuitPython every time you want to add or remove a game file. The filesystem and sketch now work in tandem.

Downloading and Compiling the Code

The code for the A2Z Machine is available on GitHub here. This project is based on the JZip 2.1 project at http://jzip.sourceforge.net/. You will also need the following libraries:

Adafruit SPIFlash – Support for FAT filesystems on SPI flash chips

Adafruit QSPI – Library for interfacing with the QSPI chip, used for the FAT filesystem (this library has since been incorporated into the SPIFlash library and is no longer needed)

mcurses – Arduino version of the ncurses library, used for  text-based user interfaces

TinyUSB (new for version 2) – Makes the ItsyBitsy M4 Express act like a thumb drive, allowing for drag and drop of Z Machine game files to the device

Create a new sketch named “a2z_machine” and copy all files except the stories folder from the GitHub project to it. Once all the libraries have been installed you can compile and upload the sketch.

Configuring Your Terminal Emulator

Note: These instructions are for PC users

Download and install the PuTTY application (other terminal emulators may work but have not been tested). After plugging in the ItsyBitsy device, determine which serial port it is being used by looking at Windows’ device manager under the “Ports (COM & LPT)” section. In PuTTY, select the connection type “Serial” and enter the port name shown in the device manager (COM10 in the screenshot). Other defaults should be sufficient, including 9600 BAUD for the speed, 80 columns and 24 rows.

Playing the Game!

Once you connect to the A2Z Machine with your terminal emulator, you should see the main screen. If not, press the F1 key to refresh the screen. You can select from 5 different retro themes by pressing the slash “/” key.

Select one of the retro themes from the list. Once a theme is selected, select a game to play using the cursor keys (the list will vary depending on which games you have stored on the ItsyBitsy filesystem):

Once you select a game by pressing <enter>, the game will begin. You can exit the game at anytime and select a different game or theme by using the command “quit” or “q” and typing “y” to confirm. You may wish to save the current game before exiting.

You can find tutorials on playing Zork and other interactive fiction games on the internet. You can also read a history of Zork on Wikipedia. Below is a brief overview from the Zork README file. In addition to this list, the commands “save” and “restore” are available to save and restore your progress in the game. A “save” is recommended prior to exploring uncharted rooms in case you unexpectedly die.

Gameplay notes
-----------------------------------------------------------------------------------------------------
The game is a text adventure and recognizes different words that you type in to
the computer. The following is a list of some (but not all) of the verbs that
you can use:

look    take
examine kill
talk    open
close   enter
exit    push
pull    lift
move    tie

You can also use compass directions to indicate that you want to move in that
direction. For example, you can type:

"go north"

or you can type

"north"

or just

"n"

Typical directions are N,S,E,W,NE,NW,SE,SW,Up,Down

To save a game, type "save" and the name of the game you want to save.

To load a game, type "restore" and the name of the game you want to load.