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.

Table 1. 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 style 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 screen 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
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)
Hex	V	Dyn	Int	Rst	Contents

Some early Version 3 files do not contain length and checksum data, hence the notation 3+.

Another view of the header

The above table is missing explicit field widths and unused bytes; here’s another view of the header that might make looking at a binary/hex dump easier to comprehend:

(It’s an open question as to whether this would be better as a 4-byte-wide display. For byte-address reasons, 16 bytes wide makes a lot of sense, but the fields are then too narrow for most field names. 8 bytes wide gives about enough room for just-intelligible abbreviation while keeping the display compact.)

The background colors represent the version that the field was introduced, on a sliding scale from green (v1) to orange (v6), with red for any fields whose meaning changes beteween versions:

And here’s a visual of the bits in the “flags” values (the “?”-suffixed fields are those that the interpreter must set to indicate available functionality):

Flags1 in Versions 1–3

Flags1 in Versions 4–6

Flags2 (first byte is the "high" word/bit byte)

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 S7.3, S7.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
2	Apple IIe
3	Macintosh
4	Amiga
5	Atari ST
6	IBM PC
7	Commodore 128
8	Commodore 64
9	Apple IIc
10	Apple IIgs
11	Tandy Color

(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).

Modern games are strongly discouraged from testing the interpreter number or interpreter version header information for any game-changing behaviour. It is rarely meaningful, and a Standard interpreter provides many better ways to query the interpreter for information.

11.1.4

[1.0] The use of bit 7 in ’Flags 1′ to signal whether timed input is available was new in the 1.0 document: see the preface.

11.1.5

[1.0] 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

[1.0][1.1] Words in the header extension table have been allocated as follows:

Table 2. Header extension format
Word	V	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)
4	5			Flags 3:
	6	*	*	0: If set, game wants to use transparency
5	5	*	*	True default foreground colour
6	5	*	*	True default background colour

Header extension visualized

11.1.7.4

[1.1] The bits in Flags 3 are set by the game to request use of a feature. If the interpreter cannot provide a feature, it must clear the relevant bit.

11.1.7.4.1

[1.1] All unused bits in Flags 3 must be cleared by the interpreter.

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 S16.

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

The bit in the header described as “requesting screen redraw” may be set by modern interpreters after, for example, resizing the “screen”; games should ideally redraw the screen if they see this bit set. This will usually mean the game clears the screen contents and rearranges borders, etc, so the bit should not be set except when necessary.

The (Version 6) sound and picture bits in Flags 1 indicate general availability of sound and graphics—ie whether the associated opcodes are available and functional.

The bits in Flags 2 should ideally be set reflecting current availability, rather than general support. In other words, if no Blorb (or other) resources for this story file have been found, or if the Blorb file contains no graphics or no sound, the corresponding bits should be cleared.

Also, it is recommended that interpreters that would prompt for an auxiliary Blorb file should do so immediately on start up if any of the “game wants to use sound/music/graphics” bits are set; this allows the bits to be cleared if no file is forthcoming, before the game starts execution. The game can then take appropriate action.