Recent Changes - Search:
Project /

Z-code

Z-CODE FILE MANIPULATIONS

2014-09-31

Recent activities with Infocom's Zork have encouraged me to become more aware of tools for running Infocom games on alternate platforms, such as Windows natively, PDP-11 RT-11 and RSTS/E, *NIX and so on. Also, as I've learned more about these games I have at last developed an understanding of the genius in the Infocom Z-machine platform, keeping that separate from the Z-code files that constitute the game itself. By porting Z-machine interpreters to the many microcomputers of the day, Infocom was able to release their games on all the support platforms immediately, without custom coding for each platform. This characteristic of the Infocom Z-machine and the laudable work of many people to uncover the Z-machine 'language' (Z-code), we now have the opportunity to run the Z-code games on many modern platforms, natively, without emulation of some historical system.

So, lately I've been running Frotz, a Z-machine targeted to *NIX system, with it running on local Linux and NetBSD systems. Most Linux distributions have a Frotz package, but for my 'oldish' NetBSD 1.5.3 running on a VAXstation, it was a fairly easy compile from source. It only requires a curses library. Or, Frotz can be compiled without curses, resulting in what the maintainer calls 'Dumb Frotz'. Dumb Frotz doesn't perform any screen manipulations, it simply generates straight TTY output, thus it can even be used with a printing terminal. There are several 'targeted' ports of Frotz that I have found useful, particularly the WindowsFrotz port, which presents a nice GUI window with choice of character fonts, colors, and easy file loading and saving using the normally expected Windows functions.

Additionally, I have been playing Zork on both my DEC Rainbow running CP/M 2.2 and my Apple II. These two cases present some opportunities for file-manipulation fun, in order to get the desired game on that platform. The key to both of the following systems, is using the original Z-machine executable, but with a different Z-code game file. Fortunately, in my work I have not found any case of executables or entire disks being check-summed in any way, thus allowing easy modification.

These methods of transferring Z-code data to and from disparate systems, creates an opportunity to build up a more complete library of games for each target system, by combining all of the Z-code game data found for various systems into a central library, then pushing them back out to each target. I have confirmed that this works between Apple II original game data and Frotz and with MS-DOS original game data with ZEMU on a PDP-11 running RT-11, and MS-DOS original game data and CP/M on the Rainbow. This confirms that the Z-code is truly portable, as long as a Z-machine executable exists on the target system.

NOTE: Though not applicable to Frotz, all of the following commentary is dependent on the various game data being of Z-code version 3 flavor only! The executable Z-machines that I have on these old micros (PC running MS-DOS, DEC Rainbow running CP/M, and Apple II with self-booting floppies) are designed for only Z-code version 3 data. When transferring Z-code between systems, first confirm that it is version 3 Z-code (data file's first byte is 0x03).

CP/M-86 (DEC Rainbow)

For example, ZORK I consists of two files that make up that game: ZORK1.CMD and ZORK1.DAT. True, the Z-code data file is separate from the Z-machine executable, but the data file name and default save game file name are both hard-coded in the binary executable. If I want to play Zork II, it would appear that I'm out of luck, even though I have the Zork II data file (Z-code) at hand from an MS-DOS distribution package.

Here the trick isn't too difficult. I can do two things to overcome this:

  1. copy in the ZORK2.DAT file, renaming it ZORK1.DAT; now I can play Zork II, but under the guise of it being a Zork I data file
  2. modify the filenames within the binary executable ZORK1.CMD, then rename ZORK1.CMD as desired

The step-by-step recipe for this second method is yet to be documented in full, but at a high level it simply consists of:

  • use a debugger or hex editor to locate the sequence 'ZORK1.DAT' followed by nulls, and replace that string with the desired string, i.e. 'ZORK2.DAT' followed by nulls,
  • make a similar change to the save file name 'ZORK1.SAV', e.g. to 'ZORK2.SAV', and,
  • rename the newly edited binary executable from ZORK1.CMD to the new game name, i.e., ZORK2.CMD

The difficulty comes in with the fact that CP/M's DDT has no save capability, so though I can modify the image in memory, there is no way to save that back to disk.

New method (2015-07-24)

Though DDT doesn't have a save capability, as it turns out, there is a way to save the memory image to a file.

  • note the ending address of the loaded binary for later use in saving the memory image
  • complete the modifications to the binary executable, as given above
  • enter 'G0' (tha's a zero) to leave DDT
  • save modified memory image with 'SAVE xx <filename>' where xx is the number of 256-byte memory pages to save

Old method

The workable method that I have used so far for permanent changes is:

  • boot the Rainbow to MS-DOS
  • copy the binary executable file from the CP/M partition or floppy using RDCPM
  • use MS-DOS's debugger to make the change and save it
  • use KERMIT to move the modified file temporarily to another host
  • lastly, reboot the system back into CP/M and 'kermit' the modified file over from the temporary host

Not altogether clean and requires reboots, etc., but it does work. I can reduce the pain somewhat by simply keeping a copy of the binary executable on the other host, modifying it when desired, then KERMIT to get it over to Rainbow running CP/M. No reboots, this way, but still requires the host external to the Rainbow.

So far, I have used this method based on a Zork I original, with Zork II and Planetfall and Leather Goddesses... with no problems. The 'new' games run fine.

Apple II

Here the real fun begins. I have located Zork I for the Apple as an ADT disk image (.DSK). In this case, the Z-machine and the Z-code game data are integrated on a self-booting floppy. There is no operating system, therefore no file-system. Just raw sectors on a floppy. The challenge comes in when I want to run a different game. Unlike the DEC Rainbow, the game data is not simply a file I can rename.

But, I have discovered a way to 'extract' the game data from the floppy, and 'inject' game data into the floppy, thus allowing me to change the Z-code game and run it on the Apple II. A little investigation shows that the Z-machine on these self-booting diskettes starts with the first sector and is sequentially laid out on a sector-by-sector basis. The Z-code data follows, and is likewise laid out sequentially. Nulls fill the rest of the floppy's unused sectors.

The trick involves disk images, rather than the real floppy. With the image, I can use several file manipulation tools to extract and inject Z-code data. Here are some key items of knowledge that are pertinent to this project:

  • ADT disk images (.DSK files) have the 256-byte sectors in so-called 'DOS sector order' meaning they are still interleaved within the file
  • Before extraction or injection of data sections of the disk, these DOS ordered sectors must be reorganized into a 'straight order'
  • After injection of new data into the disk image, the sectors must be 're-interleaved' into DOS sector order
  • On the copy of Zork I that I have. The Z-machine occupies the first 48 sectors. The Z-code data starts with sector 49 and goes from there till complete, then all subsequent sectors contain nulls.

I wrote a very simple Perl script 'Attach:fixorder.pl Δ' to help with rearranging the sectors to and from both DOS and 'straight' sector orders. So, here's the sequence on any system with Perl and the *NIX utility 'dd':

  • create a temporary file with just zeros of substantial length for later use:
    • dd if=/dev/zero bs=256 count=520 of=ZEROS.TMP
  • reorder the sectors in the original disk image to 'straight order':
    • fixorder.pl -s ZORK1.DSK ZORK1.STR
  • extract the Z-machine for later use:
    • dd if=ZORK1.STR bs=256 count=48 of=ZMACHINE.STR
  • combine the extracted Z-machine with new Z-code data followed by zeros:
    • cat ZMACHINE.STR ZORK2.DAT ZEROS.TMP > ZORK2.TMP
  • truncate the resulting file to 560-sector floppy length:
    • dd if=ZORK2.TMP bs=256 count=560 of=ZORK2.STR
  • restore the interleaved DOS sector order:
    • fixorder.pl -d ZORK2.STR ZORK2.DSK

(It is possible to simply inject the new Z-code data into ZORK1.STR without extracting the Z-machine, but take care not to overwrite the original DSK image file when returning the image to DOS sector order, thus resulting in a DSK image file.)

Now load the .DSK image in the AppleWin emulator and play, or transfer the image back to a real floppy on the Apple II using ADT.

I have used this method based on a Zork I original game, inserting Zork II, Lurking Horror, and Stationfall with no problems. The 'new' games run fine.

One last thought on the Apple II method. I could automate the process by expanding fixorder.pl to handle all of the steps, or create a new script that handles each step calling fixorder.pl as an external command. Either way would make this fairly pain free.

One other last thought. It is possible that other original Infocom game floppy images for the Apple II have the Z-code start at a sector other than sector 49. With each new 'binary executable' floppy serving as a foundation for this process, the correct starting sector should be confirmed.

NOTE: The maximum length of Z-code data on these Apple floppies is 128KB (512 sectors, 131072 bytes). The Lurking Horror, for example, is nearly this long (508 sectors, 130048 bytes) using all but four sectors, but it does fit!