3. How text and characters are encoded

Z-machine text is a sequence of ZSCII character codes (ZSCII is a system similar to ASCII: see S3.8 below). These ZSCII values are encoded into memory using a string of Z-characters. The process of converting between Z-characters and ZSCII values is given in SS3.2 to 3.7 below.

Text in memory consists of a sequence of 2-byte words. Each word is divided into three 5-bit ’Z-characters’, plus 1 bit left over, arranged as

The bit is set only on the last 2-byte word of the text, and so marks the end.

In Versions 3 and later, Z-characters 1, 2 and 3 represent abbreviations, sometimes also called ‘synonyms’ (for traditional reasons): the next Z-character indicates which abbreviation string to print. If z is the first Z-character (1, 2 or 3) and x the subsequent one, then the interpreter must look up entry 32(z-1)+x in the abbreviations table and print the string at that word address. In Version 2, Z-character 1 has this effect (but 2 and 3 do not, so there are only 32 abbreviations).

Z-character 6 from A2 means that the two subsequent Z-characters specify a ten-bit ZSCII character code: the next Z-character gives the top 5 bits and the one after the bottom 5.

The remaining Z-characters are translated into ZSCII character codes using the “alphabet table”.

Since the end-bit only comes up once every three Z-characters, a string may have to be ’padded out’ with null values. This is conventionally achieved with a sequence of 5’s, though a sequence of (for example) 4’s would work equally well.

When an interpreter is encrypting typed-in text to match against dictionary words, the following restrictions apply. Text should be converted to lower case (as a result A1 will not be needed unless the game provides its own alphabet table). Abbreviations may not be used. The pad character, if needed, must be 5. The total string length must be 6 Z-characters (in Versions 1 to 3) or 9 (Versions 4 and later): any multi-Z-character constructions should be left incomplete (rather than omitted) if there’s no room to finish them. For example, “i” is encrypted as:

The character set of the Z-machine is called ZSCII (Zork Standard Code for Information Interchange; pronounced to rhyme with “xyzzy”). ZSCII codes are 10-bit unsigned values between 0 and 1023. Story files may only legally use the values which are defined below. Note that some values are defined only for input and some only for output.

In practice the text compression factor is not really very good: for instance, 155000 characters of text squashes into 99000 bytes. (Text usually accounts for about 75% of a story file.) Encoding does at least encrypt the text so that casual browsers can’t read it. Well-chosen abbreviations will reduce total story file size by 10% or so.

The German translation of Zork I uses an alphabet table to make accented letters (from the standard extra characters set) efficient in dictionary words. In Version 6, Shogun also uses an alphabet table.

Unicode translation tables are new in Standard 1.0: in Standard 0.2, the extra characters were always mapped using the default Unicode translation table.

Note that if a random stretch of memory is accidentally printed as a string (due to an error in the story file), illegal ZSCII codes may well be printed using the 4-Z-character escape sequence. It’s helpful for interpreters to filter out any such illegal codes so that the resulting on-screen mess will not cause trouble for the terminal (e.g. by causing the interpreter to print ASCII 12, clear screen, or 7, bell sound).

The continental European quotation marks << and >> should have spacing which looks sensible either in French style <<Merci!>> or in German style >>Danke!<<.

Ideally, an interpreter should be able to read time delays (for timed input) from stream 1 (i.e., from a script file). See the remarks in S7.

The Beyond Zork story file is capable of receiving both mouse-click codes (253 and 254), listing both in its terminating characters table and treating them equally.

The extant Infocom games in Versions 4 and 5 use the control characters 1 to 31 only as follows: they all accept 10 or 13 as equivalent, except that Bureaucracy will only accept 13. Bureaucracy needs either 127 or 8 to be a delete code. No other codes are used.

Curiously, Nord ‘n’ Bert Couldn’t Make Head Nor Tail Of It and A Mind Forever Voyaging allow some letter characters to be typed in with the top bit set. That is, if reading an A, they would recognise 65 or 91 (upper or lower case) and also 193 or 219. Matthew Russotto suggests this was an accommodation for the Apple II, whose keyboard primitives returned the last key pressed in the bottom 7 bits of a byte, plus a top bit flag indicating whether or not the keyboard had been hit since last time.

In the past, not just in the Z-machine world, there has been general confusion over the rendering of ASCII/ZSCII/Latin-1/Unicode characters $27 and $60. For the Z-machine, the traditional interpretations of right-single-quote/apostrophe and left-single-quote are preferred over the modern neutral-single-quote and grave accent—see Table 2A of the Inform Designer’s Manual. $22 is a neutral double-quote.

An alternative rendering is to interpret both $27 and $60 as neutral quotes, but interpreting $60 as a grave accent is to be avoided.

No doubt aware of this confusion, Infocom never used character $60, and used $27 almost exclusively as an apostrophe—hardly any single quotes appear in Infocom games. Modern authors would do well to follow their lead.

The few Infocom games that do use single quotes use $27 for both opening and closing—but even on many of their interpreters this looked a little odd, so suggesting that $27 be a right quote introduces no extra compatibility problems.

In Version 3 and later, many of Infocom’s interpreters (and some subsequent interpreters, such as ITF’s) treat two consecutive Z-characters 4 or 5 as shift locks, contrary to the Standard. As a result, story files should not use multiple consecutive 4 or 5 codes except for padding at the end of strings and dictionary words. In any case, these shift locks are not used in dictionary words, or any of Infocom’s story files.

To handle languages like Arabic or Hebrew, text would have to be output “visually”, with manual line breaks (possibly via an in-game formatting engine).

Far eastern languages are generally straightforward, except they usually use no spaces, and line wraps can occur almost anywhere. The easiest to way to handle this would be for the game to turn off buffering. A more sophisticated game might include its own formatting engine. Also, fixed-space output is liable to be problematical with most Far Eastern fonts, which use a mixture of “full width” and “half width” forms—all half-width characters would have to be forced to full width.