The Z-Machine Standards Document

11. The format of the header

11.1

The header table summarises those locations in the Z-machine's header which an interpreter must deal with. (For further notes on traditional usage, see Appendix B.) "Hex" means the address, in hexadecimal; "V" the earliest Version to which the rule is applicable; "Dyn" means that the byte or bit may legally be changed by the game during play; "Int" means that the interpreter may change it; "Rst" means that the interpreter must set it correctly after loading the game, after a restore or after a restart.
Header format
Hex V Dyn Int Rst Contents
0 1 Version number (1 to 6)
1 3 Flags 1 (in Versions 1 to 3):
Bit 1: Status line type: 0=score/turns, 1=hours:mins
2: Story file split across two discs?
* * 4: Status line not available?
* * 5: Screen-splitting available?
* * 6: Is a variable-pitch font the default?
4 Flags 1 (from Version 4):
5 * * Bit 0: Colours available?
6 * * 1: Picture displaying available?
4 * * 2: Boldface available?
4 * * 3: Italic available?
4 * * 4: Fixed-space font available?
6 * * 5: Sound effects available?
4 * * 7: Timed keyboard input available?
4 1 Base of high memory (byte address)
6 1 Initial value of program counter (byte address)
6 Packed address of initial "main" routine
8 1 Location of dictionary (byte address)
A 1 Location of object table (byte address)
C 1 Location of global variables table (byte address)
E 1 Base of static memory (byte address)
10 1 Flags 2:
1 * * * Bit 0: Set when transcripting is on
3 * * 1: Game sets to force printing in fixed-pitch font
6 * * 2: Int sets to request status line redraw: game clears when it complies with this.
5 * * 3: If set, game wants to use pictures
5 * * 4: If set, game wants to use the UNDO opcodes
5 * * 5: If set, game wants to use a mouse
5 6: If set, game wants to use colours
5 * * 7: If set, game wants to use sound effects
6 * * 8: If set, game wants to use menus
(For bits 3,4,5,7 and 8, Int clears again if it cannot provide the requested effect.)
18 2 Location of abbreviations table (byte address)
1A 3+ Length of file (see note)
1C 3+ Checksum of file
1E 4 * * Interpreter number
1F 4 * * Interpreter version
Hex V Dyn Int Rst Contents
20 4 * * Screen height (lines): 255 means "infinite"
21 4 * * Screen width (characters)
22 5 * * Screen width in units
24 5 * * Screen height in units
26 5 * * Font width in units (defined as width of a '0')
6 * * Font height in units
27 5 * * Font height in units
6 * * Font width in units (defined as width of a '0')
28 6 Routines offset (divided by 8)
2A 6 Static strings offset (divided by 8)
2C 5 * * Default background colour
2D 5 * * Default foreground colour
2E 5 Address of terminating characters table (bytes)
30 6 * Total width in pixels of text sent to output stream 3
32 1 * * Standard revision number
34 5 Alphabet table address (bytes), or 0 for default
36 5 Header extension table address (bytes)
Some early Version 3 files do not contain length and checksum data, hence the notation 3+.

**Header format**
Hex	V	Dyn	Int	Rst	Contents
0	1				Version number (1 to 6)
1	3				Flags 1 (in Versions 1 to 3):
					Bit 1: Status line type: 0=score/turns, 1=hours:mins
					2: Story file split across two discs?
			*	*	4: Status line not available?
			*	*	5: Screen-splitting available?
			*	*	6: Is a variable-pitch font the default?
	4				Flags 1 (from Version 4):
	5		*	*	Bit 0: Colours available?
	6		*	*	1: Picture displaying available?
	4		*	*	2: Boldface available?
	4		*	*	3: Italic available?
	4		*	*	4: Fixed-space font available?
	6		*	*	5: Sound effects available?
	4		*	*	7: Timed keyboard input available?
4	1				Base of high memory (byte address)
6	1				Initial value of program counter (byte address)
	6				Packed address of initial "main" routine
8	1				Location of dictionary (byte address)
A	1				Location of object table (byte address)
C	1				Location of global variables table (byte address)
E	1				Base of static memory (byte address)
10	1				Flags 2:
	1	*	*	*	Bit 0: Set when transcripting is on
	3	*		*	1: Game sets to force printing in fixed-pitch font
	6	*	*		2: Int sets to request status line redraw: game clears when it complies with this.
	5		*	*	3: If set, game wants to use pictures
	5		*	*	4: If set, game wants to use the UNDO opcodes
	5		*	*	5: If set, game wants to use a mouse
	5				6: If set, game wants to use colours
	5		*	*	7: If set, game wants to use sound effects
	6		*	*	8: If set, game wants to use menus
					(For bits 3,4,5,7 and 8, Int clears again if it cannot provide the requested effect.)
18	2				Location of abbreviations table (byte address)
1A	3+				Length of file (see note)
1C	3+				Checksum of file
1E	4		*	*	Interpreter number
1F	4		*	*	Interpreter version
Hex	V	Dyn	Int	Rst	Contents
20	4		*	*	Screen height (lines): 255 means "infinite"
21	4		*	*	Screen width (characters)
22	5		*	*	Screen width in units
24	5		*	*	Screen height in units
26	5		*	*	Font width in units (defined as width of a '0')
	6		*	*	Font height in units
27	5		*	*	Font height in units
	6		*	*	Font width in units (defined as width of a '0')
28	6				Routines offset (divided by 8)
2A	6				Static strings offset (divided by 8)
2C	5		*	*	Default background colour
2D	5		*	*	Default foreground colour
2E	5				Address of terminating characters table (bytes)
30	6		*		Total width in pixels of text sent to output stream 3
32	1		*	*	Standard revision number
34	5				Alphabet table address (bytes), or 0 for default
36	5				Header extension table address (bytes)

11.1.1

It is illegal for a game to alter those fields not marked as "Dyn". An interpreter is therefore free to store values of such fields in its own variables.

11.1.2

The state of the transcription bit (bit 0 of Flags 2) can be changed directly by the game to turn transcribing on or off (see S 7.3, S 7.4). The interpreter must also alter it if stream 2 is turned on or off, to ensure that the bit always reflects the true state of transcribing. Note that the interpreter ensures that its value survives a restart or restore.

11.1.3

Infocom used the interpreter numbers:

   1   DECSystem-20     5   Atari ST           9   Apple IIc
   2   Apple IIe        6   IBM PC            10   Apple IIgs
   3   Macintosh        7   Commodore 128     11   Tandy Color
   4   Amiga            8   Commodore 64

(The DECSystem-20 was Infocom's own in-house mainframe.) An interpreter should choose the interpreter number most suitable for the machine it will run on. In Versions up to 5, the main consideration is that the behaviour of 'Beyond Zork' depends on the interpreter number (in terms of its usage of the character graphics font). In Version 6, the decision is more serious, as existing Infocom story files depend on interpreter number in many ways: moreover, some story files expect to be run only on the interpreters for a particular machine. (There are, for instance, specifically Amiga versions.)

11.1.3.1

Interpreter versions are conventionally ASCII codes for upper-case letters in Versions 4 and 5 (note that Infocom's Version 6 interpreters just store numbers here).

11.1.4

*** The use of bit 7 in 'Flags 1' to signal whether timed input is available is new in this document: see the preface.

11.1.5

*** If an interpreter obeys Revision n.m of this document perfectly, as far as anyone knows, then byte $32 should be written with n and byte $33 with m. If it is an earlier (non-standard) interpreter, it should leave these bytes as 0.

11.1.6

The file length stored at $1a is actually divided by a constant, depending on the Version, to make it fit into a header word. This constant is 2 for Versions 1 to 3, 4 for Versions 4 to 5 or 8 for Versions 6 and later.

11.1.7

The header extension table provides potentially unlimited room for further header information. It is a table of word entries, in which the initial word contains the number of words of data to follow.

11.1.7.1

If the interpreter needs to read a word which is beyond the length of the extension table, or the extension table doesn't exist at all, then the result is 0.

11.1.7.2

If the interpreter needs to write a word which is beyond the length of the extension table, or the extension table doesn't exist at all, then the result is that nothing happens.

11.1.7.3

*** Words in the header extension table have been allocated as follows:
Header extension format
Word V Dyn Int Rst Contents
0 5 Number of further words in table
1 5 * X-coordinate of mouse after a click
2 5 * Y-coordinate of mouse after a click
3 5 Unicode translation table address (optional)

**Header extension format**
Word	V	Dyn	Int	Rst	Contents
0	5				Number of further words in table
1	5		*		X-coordinate of mouse after a click
2	5		*		Y-coordinate of mouse after a click
3	5				Unicode translation table address (optional)

Remarks

In the Infocom period, the larger Version 3 story files would not entirely fit on a single Atari 800 disc (though they would fit on a single Apple II, or a single PC disc). Atari versions were therefore made which were identical to the normal ones except for having Flags 1 bit 2 set, and were divided into the resident part on one disc and the rest on another. (This discovery was announced by Stefan Jokisch on 26 August 1997 and sees the end of one of the very few Z-machine mysteries left when Standard 1.0 was first published.)

See the "Infocom fact sheet" for numbers and letters of the known interpreters shipped by Infocom. Interpreter versions are conventionally the upper case letters in sequence (A, B, C, ...). At present most ports of Zip use interpreter number 6, and most of ITF use number 2.

The unusual behaviour of 'Beyond Zork' concerns its character graphics: see the remarks to S 16.

The Macintosh story file for 'Zork Zero' erroneously does not set the pictures bit (Flags 2, bit 3).

Contents / Preface / Overview

Section 1 / 2 / 3 / 4 / 5 / 6 / 7 / 8 / 9 / 10 / 11 / 12 / 13 / 14 / 15 / 16

Appendix A / B / C / D / E / F