infocom/interpreters/specification/zspec02/Specification.tex

% -------------------------------------------------------------------------
%
%   The Specification of the Z-Machine
%
%   This file is formatted in the TeX typesetting language,
%   but after the initial pages of macro definitions is relatively
%   straightforward to read as plain text.
%
%   After the \end directive, the file also contains five short Inform
%   programs useful for testing compliance with the specification.
%
%   -- GAN, 951115
%
% -------------------------------------------------------------------------
% ---------------------------------------------------------------------------
% ---------------------------------------------------------------------------

\newif\iffiles\filesfalse
%  Manual macros
%
%  Page layout
%
\newif\ifshutup\shutupfalse
\newif\iflexicon\lexiconfalse
\newif\ifanswers\answersfalse
\magnification=\magstep 1
\hoffset=0.15 true in
\voffset=2\baselineskip
%
%  General hacks
%
\def\PAR{\par}
%
%  Font loading
%
\font\medfont=cmr10 scaled \magstep2
\font\bigfont=cmr10 scaled \magstep3
%\def\sectfont{\bf}
\font\sectfont=cmbx12
\def\small{\sevenrm}
\font\rhrm=cmr8
\font\rhit=cmsl8
%
%  Titles
%
\newcount\subsectno    %  Subsection number
\def\rhead{{\rhrm\topmark}}           %  The running head will go here
%
\def\newsection#1#2{%     To begin a section...
%\global\titletrue%        Declare this as a title page
%\xdef\rhead{{\rhrm #1}\quad #2}%       Initialise running head and ssn
\subsectno=0%
\iffiles
\write\conts{\string\sli\string{#1\string}\string{#2\string}\string{\the\pageno\string}}%
\fi
}
%
\def\section#1#2{\mark{}\vskip 1 true in\goodbreak
\noindent{\sectfont #1\quad #2}\bigskip\newsection{#1}{#2}\noindent\mark{#1\quad #2}}
\def\sectionx#1{\mark{}\vskip 1 true in\goodbreak
\noindent{\sectfont #1}\bigskip\newsection{}{#1}\noindent\mark{\quad #1}}
%
\def\newpage{\mark{}\vfill\eject}
%
%  Headers and footers
%
\newif\iftitle
\headline={\iftitle\hfil\global\titlefalse%
           \else{\iflexicon{\bf\firstmark}\hfil{\bf\botmark}\else%
                 \ifanswers{\hfil\ifnum\firstmark=\botmark%
                            {\rhit Answer to exercise \rhrm\firstmark}%
                            \else{\rhit Answers to exercises \rhrm\firstmark-\botmark}%
                           \fi}\else%
                 \hfil{\rhit \rhead}\fi\fi}%
           \fi}
\footline={\ifnum\pageno<0\hfil{\tenbf\romannumeral -\pageno}%
\else\hfil{\tenbf \number\pageno}\fi}
%\footline={\ifnum\pageno=1\hfil\else\hfil{\tenbf \number\pageno}\fi}
%
%  (Old date-stamping version:)
% \footline={\hfil{\rm \number\pageno}\hfil{\rm \number\day/\number\month}}
%
% If this works I'll be impressed
%

\font\ninerm=cmr9
\font\ninei=cmmi9
\font\ninesy=cmsy9
\font\ninebf=cmbx9
\font\eightbf=cmbx8
\font\ninett=cmtt9
\font\nineit=cmti9
\font\ninesl=cmsl9
\def\ninepoint{\def\rm{\fam0\ninerm}%
  \textfont0=\ninerm
  \textfont1=\ninei
  \textfont2=\ninesy
  \textfont3=\tenex
  \textfont\itfam=\nineit \def\it{\fam\itfam\nineit}%
  \textfont\slfam=\ninesl \def\sl{\fam\slfam\ninesl}%
  \textfont\ttfam=\ninett \def\tt{\fam\ttfam\ninett}%
  \textfont\bffam=\ninebf
  \normalbaselineskip=11pt
  \setbox\strutbox=\hbox{\vrule height8pt depth3pt width0pt}%
  \normalbaselines\rm}

\def\tenpoint{\def\rm{\fam0\tenrm}%
  \textfont0=\tenrm
  \textfont1=\teni
  \textfont2=\tensy
  \textfont3=\tenex
  \textfont\itfam=\tenit \def\it{\fam\itfam\tenit}%
  \textfont\slfam=\tensl \def\sl{\fam\slfam\tensl}%
  \textfont\ttfam=\tentt \def\tt{\fam\ttfam\tentt}%
  \textfont\bffam=\tenbf
  \normalbaselineskip=12pt
  \setbox\strutbox=\hbox{\vrule height8.5pt depth3.5pt width0pt}%
  \normalbaselines\rm}

\parindent=30pt
\def\inpar{\hangindent40pt\hangafter1\qquad}
\def\onpar{\par\hangindent40pt\hangafter0}

\newskip\ttglue
\ttglue=.5em plus.25em minus.15em

\def\orsign{$\mid\mid$}

\outer\def\begindisplay{\obeylines\startdisplay}
{\obeylines\gdef\startdisplay#1
  {\catcode`\^^M=5$$#1\halign\bgroup\indent##\hfil&&\qquad##\hfil\cr}}
\outer\def\enddisplay{\crcr\egroup$$}

\chardef\other=12

\def\ttverbatim{\begingroup \catcode`\\=\other \catcode`\{=\other
  \catcode`\}=\other \catcode`\$=\other \catcode`\&=\other 
  \catcode`\#=\other \catcode`\%=\other \catcode`\~=\other 
  \catcode`\_=\other \catcode`\^=\other
  \obeyspaces \obeylines \tt}
{\obeyspaces\gdef {\ }}

\outer\def\beginstt{$$\let\par=\endgraf \ttverbatim\ninett \parskip=0pt
  \catcode`\|=0 \rightskip=-5pc \ttfinish}
\outer\def\begintt{$$\let\par=\endgraf \ttverbatim \parskip=0pt
  \catcode`\|=0 \rightskip=-5pc \ttfinish}
{\catcode`\|=0 |catcode`|\=\other
  |obeylines
  |gdef|ttfinish#1^^M#2\endtt{#1|vbox{#2}|endgroup$$}}

\catcode`\|=\active
{\obeylines\gdef|{\ttverbatim\spaceskip=\ttglue\let^^M=\ \let|=\endgroup}}

\def\beginlines{\par\begingroup\nobreak\medskip\parindent=0pt
  \nobreak\ninepoint \obeylines \everypar{\strut}}
\def\endlines{\endgroup\medbreak\noindent}

\def\<#1>{\leavevmode\hbox{$\langle$#1\/$\rangle$}}

\def\dbend{{$\triangle$}}
\def\d@nger{\medbreak\begingroup\clubpenalty=10000
  \def\par{\endgraf\endgroup\medbreak} \noindent\hang\hangafter=-1   % -2
  \hbox to0pt{\hskip-\hangindent\dbend\hfill}\ninepoint}
\def\refd@nger{\par\nobreak\noindent\begingroup\clubpenalty=10000
  \def\par{\endgraf\endgroup\medbreak}\ninepoint}
\outer\def\danger{\d@nger}
\def\dd@nger{\medskip\begingroup\clubpenalty=10000
  \def\par{\endgraf\endgroup\medbreak} \noindent\hang\hangafter=-1   % -2
  \hbox to0pt{\hskip-\hangindent\dbend\kern 1pt\dbend\hfill}\ninepoint}
\outer\def\ddanger{\dd@nger}
\def\ddd@nger{\medskip\begingroup\clubpenalty=10000
  \def\par{\endgraf\endgroup\medbreak} \noindent\hang\hangafter=-1   % -2
  \hbox to0pt{\hskip-\hangindent\dbend\kern 1pt\dbend\kern 1pt\dbend\hfill}\ninepoint}
\outer\def\dddanger{\dd@nger}
\def\enddanger{\endgraf\endsubgroup}

\def\cstok#1{\leavevmode\thinspace\hbox{\vrule\vtop{\vbox{\hrule\kern1pt
       \hbox{\vphantom{\tt/}\thinspace{\tt#1}\thinspace}}
     \kern1pt\hrule}\vrule}\thinspace}

\def\rstok#1{\leavevmode\thinspace\hbox{\vrule\vtop{\vbox{\hrule\kern1pt
       \hbox{\vphantom{\rm!}\thinspace{\rm#1}\thinspace}}
     \kern1pt\hrule}\vrule}\thinspace}

\newcount\exno
\exno=0

\def\xd@nger{%
  \begingroup\def\par{\endgraf\endgroup\medbreak}\ninepoint}

\outer\def\warning{\medbreak
  \noindent\llap{$\bullet$\rm\kern.15em}%
  {\ninebf WARNING}\par\nobreak\noindent}
\outer\def\refs{\medbreak
  \noindent\llap{$\bullet$\rm\kern.15em}%
  {\eightbf REFERENCES}\refd@nger}
\outer\def\nextref{\quad$\bullet$\quad}%
\outer\def\exercise{\medbreak \global\advance\exno by 1
  \noindent\llap{$\bullet$\rm\kern.15em}%
  {\eightbf EXERCISE \bf\the\exno}\refd@nger}
%\par\noindent
\def\dexercise#1{\global\advance\exno by 1
  \medbreak\noindent\llap{$\bullet$\rm\kern.15em}%
  #1{\eightbf ~EXERCISE \bf\the\exno}\refd@nger}
%   \hfil\break}
\outer\def\dangerexercise{\xd@nger \dexercise{\dbend}}
\outer\def\ddangerexercise{\xd@nger \dexercise{\dbend\dbend}}


\newwrite\ans%
\newwrite\conts%
\iffiles
\immediate\openout\conts=conts
\fi

\iffiles\else\outer\def\answer#1{\par\medbreak}\shutuptrue\fi

\newwrite\inx
\ifshutup\else
\immediate\openout\inx=inxdata
\fi
\def\marginstyle{\sevenrm %
  \vrule height6pt depth2pt width0pt } %

\newif\ifsilent
\def\specialhat{\ifmmode\def\next{^}\else\let\next=\beginxref\fi\next}
\def\beginxref{\futurelet\next\beginxrefswitch}
\def\beginxrefswitch{\ifx\next\specialhat\let\next=\silentxref
  \else\silentfalse\let\next=\xref\fi \next}
\catcode`\^=\active \let ^=\specialhat
\def\silentxref^{\silenttrue\xref}

\newif\ifproofmode
\proofmodetrue %

\def\xref{\futurelet\next\xrefswitch}
\def\xrefswitch{\begingroup\ifx\next|\aftergroup\vxref
  \else\ifx\next\<\aftergroup\anglexref
    \else\aftergroup\normalxref \fi\fi \endgroup}
\def\vxref|{\catcode`\\=\active \futurelet\next\vxrefswitch}
\def\vxrefswitch#1|{\catcode`\\=0
  \ifx\next\empty\def\xreftype{2}%
    \def\next{{\tt\text}}%
  \else\def\xreftype{1}\def\next{{\tt\text}}\fi %
  \edef\text{#1}\makexref}
{\catcode`\|=0 \catcode`\\=\active |gdef\{}}
\def\anglexref\<#1>{\def\xreftype{3}\def\text{#1}%
  \def\next{\<\text>}\makexref} %
\def\normalxref#1{\def\xreftype{0}\def\text{#1}\let\next=\text\makexref}

\def\makexref{\ifproofmode%
  \xdef\writeit{\write\inx{\text\space!\xreftype\space
    \noexpand\number\pageno.}}\iffiles\writeit\fi
  \else\ifhmode\kern0pt \fi\fi
 \ifsilent\ignorespaces\else\next\fi}

\newdimen\fullhsize
\def\fullline{\hbox to\fullhsize}
\let\lr=L \newbox\leftcolumn

\def\doubleformat{\shipout\vbox{\makeheadline
    \fullline{\box\leftcolumn\hfil\columnbox}
    \makefootline}
  \advancepageno}
\def\tripleformat{\shipout\vbox{\makeheadline
    \fullline{\box\leftcolumn\hfil\box\midcolumn\hfil\columnbox}
    \makefootline}
  \advancepageno}
\def\columnbox{\leftline{\pagebody}}

\newbox\leftcolumn
\newbox\midcolumn
\def\beginindex{
\fullhsize=6.5true in \hsize=2.1true in
 \global\def\makeheadline{\vbox to 0pt{\vskip-22.5pt
      \fullline{\vbox to8.5pt{}\the\headline}\vss}\nointerlineskip}
 \global\def\makefootline{\baselineskip=24pt \fullline{\the\footline}}
 \output={\if L\lr
   \global\setbox\leftcolumn=\columnbox \global\let\lr=M
 \else\if M\lr
   \global\setbox\midcolumn=\columnbox \global\let\lr=R
 \else\tripleformat \global\let\lr=L\fi\fi
 \ifnum\outputpenalty>-20000 \else\dosupereject\fi}
\begingroup
  \parindent=1em \maxdepth=\maxdimen
  \def\par{\endgraf \futurelet\next\inxentry}
  \obeylines \everypar={\hangindent 2\parindent}
  \exhyphenpenalty=10000 \raggedright}
\def\inxentry{\ifx\next\sub \let\next=\subentry
  \else\ifx\next\endindex \let\next=\vfill
  \else\let\next=\mainentry \fi\fi\next}
\def\endindex{\mark{}\break\endgroup
\supereject
\if L\lr \else\null\vfill\eject\fi
\if L\lr \else\null\vfill\eject\fi
}
\let\sub=\indent \newtoks\maintoks \newtoks\subtoks
\def\mainentry#1,{\mark{}\noindent
  \maintoks={#1}\mark{\the\maintoks}#1,}
\def\subentry\sub#1,{\mark{\the\maintoks}\indent
  \subtoks={#1}\mark{\the\maintoks\sub\the\subtoks}#1,}

\def\subsection#1{\medbreak\par\noindent{\bf #1}\qquad}

%  For contents

\def\cl#1#2{\bigskip\par\noindent{\bf #1}\quad {\bf #2}}
\def\li#1#2#3{\smallskip\par\noindent\hbox to 5 in{{\bf #1}\quad #2\dotfill #3}}
\def\sli#1#2#3{\par\noindent\hbox to 5 in{\qquad\item{#1}\quad #2\dotfill #3}}
\def\fcl#1#2{\bigskip\par\noindent\hbox to 5 in{\phantom{\bf 1}\quad {\bf #1}\dotfill #2}}

% Epigrams

\def\poem{\begingroup\narrower\narrower\narrower\obeylines\ninepoint}
\def\widepoem{\begingroup\narrower\narrower\obeylines\ninepoint}
\def\verywidepoem{\begingroup\narrower\obeylines\ninepoint}
\def\quote{\medskip\begingroup\narrower\narrower\noindent\ninepoint}
\def\widequote{\medskip\begingroup\narrower\noindent\ninepoint}
\def\poemby#1#2{\par\smallskip\qquad\qquad\qquad\qquad\qquad -- #1, {\it #2}
\tenpoint\endgroup\bigskip}
\def\widepoemby#1#2{\par\smallskip\qquad\qquad\qquad -- #1, {\it #2}
\tenpoint\endgroup\bigskip}
\def\quoteby#1{\par\smallskip\qquad\qquad\qquad\qquad\qquad
 -- #1\tenpoint\endgroup\bigskip}
\def\tlwidequoteby#1#2{\par\smallskip\qquad
 -- #1\par\smallskip\qquad\qquad\qquad
 -- #2\tenpoint\endgroup\bigskip}
\def\tvquoteby#1#2{\par\smallskip\qquad
 -- #1\par\qquad\qquad\quad
 \phantom{--} #2\tenpoint\endgroup\bigskip}
\def\endquote{\par\tenpoint\endgroup\medskip}

%
%  End of macros

\def\subtitle#1{\bigbreak\noindent{\bf #1}\medskip}
\newdimen\stepin
\newdimen\tstepin
\stepin=60pt
\def\block#1{\par%\rlap{{\tt #1}}
\hangindent\stepin\hangafter0\noindent\strut\llap{\hbox to\stepin{{\tt #1}\hfill}}%
\noindent}
\def\continue{\block{}}
\newcount\sectno
\stepin=40pt
\def\orm{\smallskip\par\noindent\hangindent=0pt}
\def\frm{\par\parindent=20pt\hangindent=20pt}
\def\sp#1{\smallskip\noindent {\bf{\the\sectno.#1}}\quad\hangindent=20pt}
\def\nsp#1{\medskip\sp{#1}}
\def\specs#1#2{\tenpoint\section{#1}{#2}\sectno=#1}
\def\remarks{\medskip\ninepoint\noindent {\sl Remarks.}\qquad}
\pageno=2

% ---------------------------------------------------------------------------
% ---------------------------------------------------------------------------
% ---------------------------------------------------------------------------

\section{}{Preface}

The Z-machine was created on a coffee table in Pittsburgh in 1979.  It
is an imaginary computer whose programs are adventure games, and is
well-adapted to its task, implementing complex games remarkably compactly. 
They were still perhaps 100K long and the Z-machine seems to have made the
first usage of virtual memory on a microcomputer.  Further ahead of its time
was the ability to efficiently save and restore the entire execution state
(something we would do well to rediscover as parallel processing takes
over).

The design's cardinal principle is that any game is 100\% portable to
different computers: that is, any legal program exactly determines its
behaviour.  This portability is largely made possible by a willingness to
constrain maximum as well as minimum levels of performance (for instance,
dynamic memory allocation is impossible) and by a very primitive
operating-system interface (so file-naming issues hardly arise).  The
strategy is the opposite extreme to that of the C language, which sacrifices
predictable behaviour for performance: for instance, a programmer never
knows how many bits will make up an |int| or whether |char| will be signed.

But this is not a historical or theoretical paper, because the Z-machine is
widely used in practice to play Infocom and Inform-produced games.  It is a
standards document which aims to exactly describe the correct behaviour, and
is a variorum description in that it describes every different Version of
the machine.  (However, the Version 6 standard will remain provisional until
we have more experience with it.)

\subtitle{Why do we need a ``standards'' document?}

Since the end of the 1980s, interpreters have been in the public domain
which almost properly implement the Z-machine.  Good portable source code
for these has twice been published.  Each interpreter was then ported to
many different machines, where its behaviour was subtly altered, usually
because the porter noticed a missing feature and added it, or had to guess
something.  The ports have grown elaborate and corrections are now difficult
to propagate.  The casual user who downloads an interpreter cannot be sure
how accurate it will be: a ``new'' interpreter (with a beautiful new user
interface) may be built on a partly-repaired core which is five years old. 
One reason for a standard, then, is to increase the pressure to return to a
good common release.  Players will know what to ask for (can you get
interpreter 1.1 for the Mac?) and porters will be aware if the core has
changed.

More fundamentally, the problem has changed.  Until 1993 there were only
about 130 story files known, variant forms of 35 games and a few oddments,
all produced by the same compiler's code generator.  An interpreter could
safely be incomplete.  For instance, the |not| opcode was unnecessary
since it never occurred in any game.  Today there is a quite large base of
Inform users and many more games will be in circulation: and designers of
these new games want to know what they can depend on.  There is also
pressure for future extension of the format, so a game itself will need to
know what kind of interpreter is running it.

\subtitle{So what is ``standard''?}

To call itself ``Standard'', an interpreter should (as far as anyone knows)
obey this document exactly for every Version of the Z-machine it claims to
interpret.  (There's no problem with a standard interpreter which interprets
Version 5 only, for instance.)  Each edition of this document will be given
a Revision number (from 1.0 upwards), somewhat like the JFIF identification
number used by the JPEG standard.  A standard interpreter should communicate
the revision number it obeys in three ways:

\item{(a)} To someone downloading it from an FTP site or bulletin board:
by including it in its filename.
\item{(b)} To the player: for instance by means of an ``information'' option
on a menu, or in an initialisation sequence.
\item{(c)} To the game: by writing it into bytes in the header which were
always left zero before this standard was devised (see \S 11).  A game
compiled with Inform library 5/12 or later prints the revision number in its
banner (if this isn't 0.0).

\noindent Few arbitrary choices have been made in writing this document.  On
the few points where Infocom's own shipped interpreters disagree it has
usually been possible to decide which was ``correct''.  Elsewhere, minimum
levels of performance have been invented where necessary.  (For example, a
minimum call-stack size is needed for programmers to be sure of what level
of recursion is safe.  The call-stack size currently used by |Zip| has
been taken as the standard.)

Existing interpreters are close to the standard already.  Most ``difficult''
features (colours, fonts, sound effects, pictures, etc.) are optional, so
that a port only needs to set some header bit to indicate that it can't
oblige.  The big exception is timed input (in which an interrupt routine is
run every few tenths of a second while the player is deciding what to type). 
Some ports can't manage this for operating-system reasons, others can but
don't because it's too much trouble.  In Infocom's specification the feature
is mandatory, but many ports of |Zip| ignore it.  In this document it is
optional and a new header bit has been allocated: see \S 11.

The very few paragraphs which actually extend the Infocom format, such as
the one describing this header bit, are marked |***|.

\subtitle{Terminology}

It is assumed that the reader is familiar with terms like `object', `tree',
`attribute', `property', `local and global variable'.  (See Chapter I of the
{\sl Inform Designer's Manual} for explanation of these.)

So far, eight Versions of the Z-machine exist, and the first byte of any
``story file'' (that is: any game program in the Infocom format) gives the
Version number it must be interpreted under.

The opcode names used in this document are those used by Inform 5.4 and
later.  The names are extended from those chosen by Mark Howell for his
disassembler |Txd| and were agreed on between him and the author as
a standard set.  We hope this will provide interpreter writers and
others with a common lexicon, and it would be helpful if future interpreter
sources use these names internally.

Hexadecimal numbers are written with an initial dollar, as in |$ff|, while
binary numbers are written with a double-dollar as in |$$11011|, according
to Inform conventions.  The bits in a byte are numbered 0 to 7, 0 being
the least significant and the top bit, 7, the most.

\subtitle{Where are all the grammar tables?}

The Z-machine has some lexical acuity but it doesn't contain a full parser:
it's like a computer without an operating system.
A game program has to contain its own parser
and the tables this uses are not part of the formal Z-machine specification.
(The Infocom games have similar parsing table formats since all the
Versions 1 to 5 games used a parser which slowly evolved from the
`Zork I' parser.)  Inform's parsing table
format is documented in the {\sl Inform Technical Manual}.  For the usual
format of Infocom's parsing tables, see the C source code to Mark Howell's
utility ``Infodump''.

\subtitle{Acknowledgements}

\quote
     There is an obvious resemblance between an unreadable script
     and a secret code; similar methods can be employed to break
     both.  But the differences must not be overlooked.  The code is
     deliberately designed to baffle the investigator; the script
     is only puzzling by accident.
\poemby{John Chadwick}{The Decipherment of Linear B}

The Z-machine was originally devised by Joel Berez and Marc Blank in 1979.
Marc Blank made most of the Version 4 extensions, and Version 5 was created
by Dave Lebling (with contributions from others including Brian Moriarty,
Duncan Blanchard and Linde Dynneson).  Version 6 was largely the work of Tim
Anderson and Dave Lebling.

In the reverse direction, decipherment is mostly due to the InfoTaskForce
(David Beazley, George Janczuk, Peter Lisle, Russell Hoare and Chris Tham),
Matthias Pfaller, Mike Threepoint, Mark Howell and Paul David Doherty. 
(Only a few of the pieces in the jigsaw were placed by myself.)

I gratefully acknowledge the help of Paul David Doherty and Mark Howell, who
each drafts of this paper and sent back detailed corrections; also, of
Stefan Jokisch and Marnix Klooster who have put a great deal of work into
the fine detail of the specification; and of all those who commented on
the circulated draft, whose comments were mainly presentational but no less
important for that.  Mistakes and misunderstandings remain my own.

\medskip
\hbox to\hsize{\hfill\it Graham Nelson}
\hbox to\hsize{\hfill\it St Anne's College, Oxford}
\hbox to\hsize{\hfill\it 15 November 1995}
\medskip

\newpage

% ----------------------------------------------------------------------------

\specs{1}{The memory map}
\sp{1} The memory map of the Z-machine is an array of bytes with
``byte addresses'' running from 0 upwards.  This is divided into
three regions: ``dynamic'', ``static'' and ``high''.  Dynamic
memory begins from byte address |$00000| and runs up to the byte
before the byte address stored in the word at |$0e| in the header.
(Dynamic memory must contain at least 64 bytes.)  Static memory
follows immediately on.  Its extent is not defined in the header
(or anywhere else), though it must end by the last byte of the
story file or by byte address |$0ffff| (whichever is lower).
High memory begins at the ``high memory mark'' (the byte address
stored in the word at |$04| in the header) and continues to the
end of the story file.  The bottom of high memory may overlap with
the top of static memory (but not with dynamic memory).

\sp{1.1} Dynamic memory can be read or written to (either directly,
using |loadb|, |loadw|, |storeb| and |storew|, or indirectly with
opcodes such as |insert_obj| and |remove_obj|).

\sp{1.1.1} By tradition, the first 64 bytes are known as the
``header''.  The contents of this are given later but note that games
are not permitted to alter many bits inside it.

\sp{1.1.2} It is legal for games to alter any of the tables stored
in dynamic memory above the header, provided they leave the tables
in legal states.

\sp{1.2} Static memory can be read using the opcodes |loadb| and
|loadw|.  It is illegal for a game to attempt to write to static
memory.

\sp{1.3} Except for its (possible) overlap with static memory,
high memory cannot be directly accessed at all by a
game program.  It contains routines, which can be called,
and strings, which can be printed using |print_paddr|.

\sp{1.4} The maximum permitted length of a story file depends
on the Version, as follows:
$$ \matrix{{\rm V}1-3 & {\rm V}4-5  & {\rm V}6 & {\rm V}7 & {\rm V}8\cr
                  128 &   256       &   576    &   320    &   512\cr} $$

\nsp{2} There are three kinds of address in the Z-machine, all of
which can be stored in a 2-byte number: byte addresses, word
addresses and packed addresses.

\sp{2.1} A byte address specifies a byte in memory in the range 0
up to the last byte of static memory.

\sp{2.2} A word address specifies an even address in the bottom
128K of memory (by giving the address divided by 2).  (Word addresses
are used only in the abbreviations table.)

\sp{2.3} |***| A packed address specifies where a routine or string begins
in high memory.  Given a packed address $P$, the formula to obtain the
corresponding byte address $B$ is:
$$ B = \cases { 2P & Versions 1, 2 and 3\cr
                4P & Versions 4 and 5\cr
                4(P+R_O) & Versions 6 and 7, for routine calls\cr
                4(P+S_O) & Versions 6 and 7, for {\tt print\_paddr}\cr
                8P & Version 8\cr
} $$
$R_O$ and $S_O$ are the routine and strings offsets (specified in the
header as words at |$28| and |$2a|, respectively).

% ----------------------------------------------------------------------------
\topinsert
\centerline{\sl An example memory map of a small game}
\medskip
$$ \vbox{\offinterlineskip
\hrule
\halign{\vrule#&\strut\quad{\it #}\hfil\quad&\hfil # \quad&%
\vrule#&\strut\quad\hfil#\hfil\quad&\vrule#\cr
height2pt&\omit&\omit&&\omit&\cr
&& Start && Contains &\cr
height2pt&\omit&\omit&&\omit&\cr
\noalign{\hrule}
height2pt&\omit&\omit&&\omit&\cr
& Dynamic& |00000| && header &\cr
&        & |00040| && abbreviation strings &\cr
&        & |00042| && abbreviation table &\cr
&        & |00102| && property defaults &\cr
&        & |00140| && objects &\cr
&        & |002f0| && object descriptions &\cr
&        &         && and properties &\cr
&        & |006e3| && global variables &\cr
&        & |008c3| && arrays &\cr
& Static & |00b48| && grammar table &\cr
&        & |010a7| && actions table &\cr
&        & |01153| && preactions table &\cr
&        & |01201| && adjectives table &\cr
&        & |0124d| && dictionary &\cr
& High   & |01a0a| && Z-code &\cr
&        & |05d56| && static strings &\cr
&        & |06ae6| && end of file &\cr
height2pt&\omit&\omit&&\omit&\cr
}\hrule}$$
\endinsert

\remarks
Inform never compiles any overlap between static and high memory
(it places all data tables in dynamic memory).  However, many
Infocom games group tables of static data just above the high
memory mark, before routines begin; some, such as `Nord 'n'
Bert...', interleave static data between routines, so that static
memory actually overlaps code; and a few, such as `Seastalker'
release 15, even contain routines placed below the high memory
mark.  (The original idea behind the high memory mark was that
everything below it should be stored in the interpreter's RAM, while
what was above could reasonably be kept in ``virtual memory'', i.e.,
loaded off disc as needed.)

Note that the total of dynamic plus static memory must not exceed 64K.
(In fact, 64K minus 2 bytes.)  This is the most serious limitation
on the Z-machine (though it has not yet been reached by anyone).

Throughout the specification, Versions 7 and 8 are identical
to Version 5 except as stated at 1.1.4 and 1.2.3 above.

\newpage

% ----------------------------------------------------------------------------

\specs{2}{Numbers and arithmetic}

\sp{1} In the Z-machine, numbers are usually stored in 2 bytes
(in the form most-significant-byte first, then least-significant)
and hold any value in the range |$0000| to |$ffff| (0 to 65535
decimal).

\nsp{2} These values are sometimes regarded as signed, in the range
$-32768$ to $32767$.  In effect $-n$ is stored as $65536-n$
and so the top bit is the sign bit.

\sp{2.1} The operations of numerical comparison, multiplication,
addition, subtraction and printing of numbers are signed; bitwise
operations, division and remainder-after-division are unsigned.
(In particular, since comparison is signed, it is unsafe to compare
two addresses using simply |jl| and |jg|.)

\nsp{3} Arithmetic errors:

\sp{3.1} It is illegal to divide by 0 (or to ask for remainder after
division by 0) and an interpreter should halt with an error message
if this occurs.

\sp{3.2} Formally it has never been specified what the result of an
out-of-range calculation should be.  The author suggests that the
result should be reduced modulo |$10000|.

\nsp{4} The Z-machine needs a random number generator which at any time
has one of two states, ``random'' and ``predictable''.  When the game
starts or restarts the state becomes ``random''.  Ideally the generator
should not produce identical sequences after each restart.

\sp{4.1} When ``random'', it must be capable of generating a uniformly
random integer in the range $1\leq x\leq n$, for any value
$1\leq n\leq 32767$.  Any method can be used for this (for instance,
using the host computer's clock time in milliseconds).  The uniformity
of randomness should be optimised for low values of $n$ (say, up to
100 or so) and it is especially important to avoid regular patterns
appearing in remainders after division (most crudely, being alternately
odd and even).

\sp{4.2} The generator is switched into ``predictable'' state with a
seed value.  On any two occasions when the same seed is sown, identical
sequences of values must result (for an indefinite period) until
the generator is switched back into ``random'' mode.  The generator
should cope well with very low seed values, such as 10, and should not
depend on the seed containing many non-zero bits.

\sp{4.3} The interpreter is permitted to switch between these states
on request of the player.  (This is useful for testing purposes.)

\remarks
It is dangerous to rely on the ANSI C random number routines, as some
implementations of these are very poor.  This has made some games (in
particular, `Balances') unwinnable on some Unix ports of |Zip|.

The author suggests the following algorithm:
\item{1.} In ``random'' mode, the generator uses the host computer's
clock to obtain a random sequence of bits.
\item{2.} In ``predictable'' mode, the generator should store the
seed value $S$.  If $S<1000$ it should then internally generate
$$ 1, 2, 3, ..., S, 1, 2, 3, ..., S, 1, ... $$
so that |random n| produces the next entry in this sequence modulo $n$.
If $S\geq 1000$ then $S$ is used as a seed in a standard seeded
random-number generator.

\par\noindent (The rising sequence is useful for testing, since it will
produce all possible values in sequence.  On the other hand, a seeded
but fairly random generator is useful for testing entire scripts.)

% ----------------------------------------------------------------------------

\specs{3}{How text is encoded and printed}

\quote
    This technique is similar to the five-bit Baudot code, which
    was used by early Teletypes before ASCII was invented.
\endquote
\quote
    \quad -- Marc S. Blank and S. W. Galley, {\sl How to Fit a Large Program Into
a Small Machine}
\endquote

\sp{1} A string of encoded text is stored as a sequence of 2-byte
words.  Each of these is divided into three 5-bit `Z-characters', plus
1 bit left over, arranged as
\orm\beginstt
   --first byte-------   --second byte---
   7    6 5 4 3 2  1 0   7 6 5  4 3 2 1 0
   bit  --first--  --second---  --third--
\endtt\frm
The bit is set only on the last 2-byte word of the text, and so marks the
end.

\nsp{2} There are three `alphabets', A0 (lower case), A1 (upper case) and
A2 (punctuation) and during printing one of these is current at any given
time.  Initially A0 is current.  The meaning of a Z-character may depend on
which alphabet is current.

\sp{2.1} In Versions 1 and 2, the current alphabet can be any of the
three.  The Z-characters 2 and 3 are called `shift' characters and change
the alphabet for the next character only.  The new alphabet depends on
what the current one is:
\orm\beginstt
             from A0  from A1  from A2
  Z-char 2      A1       A2       A0
  Z-char 3      A2       A0       A1
\endtt\frm
Z-characters 4 and 5 permanently change alphabet, according to the
same table, and are called `shift lock' characters.

\sp{2.2} In Versions 3 and later, the current alphabet is always A0
unless changed for 1 character only: Z-characters 4 and 5 are shift
characters.  Thus 4 means ``the next character is in A1'' and 5 means
``the next is in A2''.  There are no shift lock characters.

\sp{2.3} An indefinite sequence of shift or shift lock characters is
legal (but prints nothing).

\nsp{3} 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).

\sp{3.1} Abbreviation string-printing follows all the rules of this section
except that an abbreviation string must not itself use abbreviations and
must not end with an incomplete multi-Z-character construction (see \S 3.6.1
below).

\nsp{4} Z-character 6 from A2 means that the two subsequent Z-characters
specify a ten-bit character code: the next Z-character gives the top 5
bits and the one after the bottom 5.  As detailed below, this is
printed using an extended form of the ASCII standard (for seven-bit
character codes).

\sp{4.1} Some Inform users require unusual accented characters (in one
case, Chinese characters).  Inform is able to produce `ASCII' values
which use the full 10 bits (using the |@@| string escape).  Game
designers may want to be able to modify the interpreter to print
something suitable when a value of 256 or above is found, and interpreter
writers are asked to make this easy.

\sp{4.1.1} The author wishes to reserve the `ASCII' values
768 to 1023 for future specification.  (One idea would be that
such a code causes a routine in Z-code to be called.  This would allow
much greater flexibility in variable printing.)

\sp{4.2} ASCII ``control codes'' in the range 0 to 31 are illegal
(i.e. should not be printed in any story file) except as follows:

\sp{4.2.1} Character 0 (ASCII ``null'') is legal but prints nothing.

\sp{4.2.2} Character 13 (``carriage return'') prints a newline.

\sp{4.2.3} In Version 6, character 9 (``tab'') at the start of a screen line
should print a paragraph indentation suitable for the font being used: if it
is printed in the middle of a screen line, it should be a space.  Character
11 (``cursor up'') should be printed as a suitable gap between two
sentences (in the same way that typographers normally place larger spaces
after the full stops ending sentences than after words or commas).

\sp{4.3} Character codes between 32 (``space'') and 126 (``tilde'') are
legal and are printed from the standard ASCII character set:
\orm\beginstt
      0123456789abcdef0123456789abcdef
      --------------------------------
 $20   !"#$%&'()*+,-./0123456789:;<=>?
 $40  @ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_
 $60  `abcdefghijklmnopqrstuvwxyz{!}~ 
      --------------------------------
\endtt\frm
In particular code |$23| (35 decimal) is a hash mark, not a pound sign.
(Code |$7c| (124 decimal) is a vertical stroke which is shown as |!|
here for typesetting reasons.)  Character 127 (``delete'') is illegal.

\sp{4.4} The `ASCII' values between 128 and 154 are at present
undefined: undefined character values should be printed as question
marks.  The range 155 to 251 is reserved for European accented
characters, but 220 to 251 are undefined.  Accented characters should
either be printed from a suitable font (they are all taken from the
`ISO Latin 1' standard set) or transliterated into plain text as in
the following table:
\orm\beginstt
155:  a-umlaut      ae            191:  a-circumflex      a
156:  o-unlaut      oe            192:  e-circumflex      e
157:  u-umlaut      ue            193:  i-circumflex      i
158:  A-umlaut      Ae            194:  o-circumflex      o
159:  O-umlaut      Oe            195:  u-circumflex      u
160:  U-umlaut      Ue            196:  A-circumflex      A
161:  sz-ligature   ss            197:  E-circumflex      E
162:  quotation     << or "       198:  I-circumflex      I
163:    marks       >> or "       199:  O-circumflex      O
164:  e-umlaut      e             200:  U-circumflex      U
165:  i-umlaut      i             201:  a-ring            a
166:  y-umlaut      y             202:  A-ring            A
167:  E-umlaut      E             203:  o-slash           o
168:  I-umlaut      I             204:  O-slash           O
169:  a-acute       a             205:  a-tilde           a
170:  e-acute       e             206:  n-tilde           n
171:  i-acute       i             207:  o-tilde           o
172:  o-acute       o             208:  A-tilde           A
173:  u-acute       u             209:  N-tilde           N
174:  y-acute       y             210:  O-tilde           O
175:  A-acute       A             211:  ae-ligature       ae
176:  E-acute       E             212:  AE-ligature       AE
177:  I-acute       I             213:  c-cedilla         c
178:  O-acute       O             214:  C-cedilla         C
179:  U-acute       U             215:  Icelandic thorn   th
180:  Y-acute       Y             216:  Icelandic eth     th
181:  a-grave       a             217:  Icelandic Thorn   Th
182:  e-grave       e             218:  Icelandic Eth     Th
183:  i-grave       i             219:  pound symbol      L
184:  o-grave       o
185:  u-grave       u
186:  A-grave       A
187:  E-grave       E
188:  I-grave       I
189:  O-grave       O
190:  U-grave       U
\endtt\frm
|***| The values from 164 onward are defined for the first time
in this standard.  (Note that all these values are the same as the
keyboard input character codes for the same letters.)

\sp{4.5} The `ASCII' values 252 to 255 are illegal, not undefined.

\nsp{5} The remaining Z-characters translate directly into printed
characters:

\sp{5.1} The Z-character 0 is printed as a space.

\sp{5.2} In Version 1, Z-character 1 is printed as a new-line.

\sp{5.3} In Versions 2 and later, Z-characters in the range 6 to 31
depend on the current alphabet.  Except for character 6 in A2, they
are printed as:
\orm\beginstt
   Z-char 6789abcdef0123456789abcdef
current   --------------------------
  A0      abcdefghijklmnopqrstuvwxyz
  A1      ABCDEFGHIJKLMNOPQRSTUVWXYZ
  A2       ^0123456789.,!?_#'"/\-:()
          --------------------------
\endtt\frm
(Character 7 in A2, written here as a circumflex |^|, is a new-line.)

\sp{5.4} Version 1 has the same table except that A2 (needing no
new-line) accommodates the |<| character as well.  It has the form:
\orm\beginstt
          6789abcdef0123456789abcdef
          --------------------------
  A2       0123456789.,!?_#'"/\<-:()
          --------------------------
\endtt\frm

\sp{5.5} In Versions 5 and later, a game may replace the above
table by providing its own ``character set table''.  It does this
by giving the byte address of such a table in the word at |$34| in
the header.  (If this byte address is 0, then the default table
above is used.)

\sp{5.5.1} The character set table consists of 78 bytes arranged
as 3 blocks of 26 ASCII values, translating Z-characters 6 to 31
for alphabets A0, A1 and A2.  Z-characters 6 and 7 of A2, however,
are still translated as escape and newline codes (as above).

\nsp{6} 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.

\sp{6.1} It is legal for the string to end while a multi-Z-character
construction is incomplete: for instance, after only the top half of
an ASCII value has been given.  The partial construction is simply
ignored.  (This can happen in printing dictionary words which have
been guillotined to the dictionary resolution of 6 or 9 Z-characters.)

\nsp{7} When encrypting text for a dictionary word: A1 may not be
used; nor may abbreviations; the pad character, if needed, must be 5; and
the total string length must be 6 Z-characters (in Versions 1 to 3) or 9
(Versions 4 and later).  For example, ``i'' is encrypted as
\begindisplay
14, 5, 5, 5, 5, 5, 5, 5, 5\quad |$48a5| |$14a5| |$94a5|\cr
\enddisplay

\remarks 
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 a character set table for accented
letters and is illegible on interpreters (like |ITF|) which do not implement
this feature.  (`Shogun' also needs the character set table.)

It is helpful for an interpreter to filter out any ASCII control
characters other than those explicitly legalised above, as this makes
run-time crashes of the ``printing random text'' kind much less
severe for the terminal.

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

Further accented characters may be allocated codes later.  Other graphical
or unusual characters are best handled by creating a new font (see \S 16
for an example font).

% ----------------------------------------------------------------------------

\specs{4}{How instructions are encoded}

\widepoem
We do but teach bloody instructions
Which, being taught, return to plague th' inventor
\poemby{Shakespeare}{Macbeth}

\sp{1} A single Z-machine instruction consists of the following
sections (and in the order shown):
\orm\beginstt
  Opcode               1 or 2 bytes
  (Types of operands)  1 or 2 bytes: 4 or 8 2-bit fields
  Operands             Between 0 and 8 of these: each 1 or 2 bytes
  (Store variable)     1 byte
  (Branch offset)      1 or 2 bytes
  (Text to print)      An encoded string (of unlimited length)
\endtt\frm
Bracketed sections are not present in all opcodes.  (A few opcodes
take both ``store'' and ``branch''.)

\nsp{2} There are four `types' of operand.  These are often specified
by a number stored in 2 binary digits:
\orm\beginstt
  $$00    Large constant (0 to 65535)    2 bytes
  $$01    Small constant (0 to 255)      1 byte
  $$10    Variable                       1 byte
  $$11    Omitted altogether             0 bytes
\endtt\frm

\sp{2.1} Large constants, like all 2-byte words of data in the Z-machine,
are stored with most significant byte first (e.g. |$2478| is stored as
|$24| followed by |$78|).  A `large constant' may in fact be a small
number.

\sp{2.2} Variable number |$00| refers to the top of the stack,
|$01| to |$0f| mean the local variables of the current routine
and |$10| to |$ff| mean the global variables.  It is illegal to
refer to local variables which do not exist for the current routine
(there may even be none).

\sp{2.3} The type `Variable' really means ``variable by value''.  Some
instructions take as an operand a ``variable by reference'': for instance,
|inc| has one operand, the reference number of a variable to increment.
This operand usually has type `Small constant' (and Inform automatically
assembles a line like |@inc turns| by writing the operand |turns| as
a small constant with value the reference number of the variable |turns|).

\nsp{3} Each instruction has a form (long, short, extended or variable)
and an operand count (0OP, 1OP, 2OP or VAR).
If the top two bits of the opcode are |$$11| the form is variable;
if |$$10|, the form is short.  If the opcode is 190 (|$BE| in hexadecimal)
and the version is 5 or later, the form is ``extended''.  Otherwise, the
form is ``long''.

\sp{3.1} In short form, bits 4 and 5 of the opcode byte give an operand
type as above.  If this is |$11| then the operand count is
0OP; otherwise, 1OP.  In either case the opcode number is
given in the bottom 4 bits.

\sp{3.2} In long form the operand count is always 2OP.  The opcode number
is given in the bottom 5 bits.

\sp{3.3} In variable form, if bit 5 is 0 then the count is 2OP;
if it is 1, then the count is VAR.  The opcode number is given
in the bottom 5 bits.

\sp{3.4} In extended form, the operand count is VAR.  The opcode number
is given in a second opcode byte.

\nsp{4} Next, the types of the operands are specified.

\sp{4.1} In short form, bits 4 and 5 of the opcode give the type.

\sp{4.2} In long form, bit 6 of the opcode gives the type of
the first operand, bit 5 of the second.  A value of 0 means a small
constant and 1 means a variable.  (If a 2OP instruction needs a
large constant as operand, then it should be assembled in variable
rather than long form.)

\sp{4.3} In variable or extended forms, a byte of 4 operand types is
given next.  This contains 4 2-bit fields: bits 6 and 7 are the first
field, bits 0 and 1 the fourth.  The values are operand types as above.
Once one type has been given as `omitted', all subsequent ones must
be.  Example: |$$00101111| means large constant followed by variable
(and no third or fourth opcode).

\sp{4.3.1} In the special case of the ``double variable'' VAR opcodes
|call_vs2| and |call_vn2| (opcode numbers 12 and 26), a second byte
of types is given, containing the types for the next four operands.

\nsp{5} The operands are given next.  Operand counts of 0OP, 1OP or 2OP
require 0, 1 or 2 operands to be given, respectively.  If the count is VAR,
there must be as many operands as there were types other than `omitted'.

\sp{5.1} Note that only |call_vs2| and |call_vn2| can have more than 4
operands, and no instruction can have more than 8.

\nsp{6} ``Store'' instructions return a value: e.g., |mul| multiplies
its two operands together.  Such instructions must be followed by a
single byte giving the variable number of where to put the result.

\nsp{7} Instructions which test a condition are called ``branch''
instructions.  The branch information is stored in one or two bytes,
indicating what to do with the result of the test.  If bit 7 of
the first byte is 0, a branch occurs when the condition was false;
if 1, then branch is on true.  If bit 6 is set, then the branch
occupies 1 byte only, and the ``offset'' is in the range 0 to 63,
given in the bottom 6 bits.  If bit 6 is clear, then the offset is
a signed 14-bit number given in bits 0 to 5 of the first byte
followed by all 8 of the second.

\sp{7.1} An offset of 0 means ``return false from the current
routine'', and 1 means ``return true from the current routine''.

\sp{7.2} Otherwise, a branch moves execution to the instruction at
address
\orm\beginstt
  Address after branch data + Offset - 2.
\endtt\frm

\nsp{8} Two opcodes, |print| and |print_ret|, are followed by a text
string.  This is stored according to the usual rules: in particular
execution continues after the last 2-byte word of text (the one with
top bit set).

\remarks
Some opcodes have type VAR only because the available codes for
the other types had run out; |print_char|, for instance.  Others, especially
|call|, need the flexibility to have between 1 and 4 operands.

The Inform assembler can assemble branches in either form, but the compiler
always writes 2-byte branch data and never uses offset values of 0 or 1.
(The computation involved in achieving these optimisations outweighs the
slight gain.)

The disassembler |Txd| numbers locals from 0 to 14 and globals from
0 to 239 in its output (corresponding to variable numbers 1 to 15, and
16 to 255, respectively).

The branch formula is sensible because in the natural implementation,
the program counter is at the address after the branch data when the branch
takes place: thus it can be regarded as
\beginstt
  PC = PC + Offset - 2.
\endtt
If the rule were simply ``add the offset'' then, since the offset couldn't
be 0 or 1 (because of the return-false and return-true values), we would
never be able to skip past a 1-byte instruction (say, a 0OP like |quit|),
or specify the branch ``don't branch at all'' (sometimes useful to ignore
the result of the test altogether).  Subtracting 2 means that the only
effects we can't achieve are
\beginstt
  PC = PC - 1     and     PC = PC - 2
\endtt
and we would never want these anyway, since they would put the program
counter somewhere back inside the same instruction, with horrid
consequences.

\bigskip\noindent{\sl On disassembly}
\medskip
\noindent Briefly, the first byte of an instruction can be decoded
using the following table:
\beginstt
  $00 -- $1f  long      2OP     small constant, small constant
  $20 -- $3f  long      2OP     small constant, variable
  $40 -- $5f  long      2OP     variable, small constant
  $60 -- $7f  long      2OP     variable, variable
  $80 -- $8f  short     1OP     large constant
  $90 -- $9f  short     1OP     small constant
  $a0 -- $af  short     1OP     variable
  $b0 -- $bf  short     0OP
  except $be  extended opcode given in next byte
  $c0 -- $df  variable  2OP     (operand types in next byte)
  $e0 -- $ff  variable  VAR     (operand types in next byte(s))
\endtt
Here is an example disassembly:
\beginlines
|  @inc_chk c 0 label;    05 02 00 d4|
|      long form; count 2OP; opcode number 5; operands:|
|          02     small constant (referring to variable c)|
|          00     small constant 0|
|      branch if true: 1-byte offset, 20 (since label is|
|      18 bytes forward from here).|
|  @print "Hello.^";      b2 11 aa 46 34 16 45 9c a5 |
|      short form; count 0OP.|
|      literal string, Z-chars: 4 13 10  17 17 20  5 18 5  7 5 5.|
|  @mul 1000 c sp;        d6 1f 03 e8 02 00|
|      variable form; count 2OP; opcode number 22; operands:|
|          03 e8  long constant (1000 decimal)|
|          02     variable c|
|      store result to stack pointer (var number 00).|
|  @call_1n Message;      8f 01 56|
|      short form; count 1OP; opcode number 15; operand:|
|          01 56  long constant (packed address of routine)|
|  .label;|
\endlines

% ----------------------------------------------------------------------------

\specs{5}{How routines are encoded}

\sp{1} A routine is required to begin at an address in memory which
can be represented by a packed address (for instance, in Version 5
it must occur at a byte address which is divisible by 4).

\nsp{2} A routine begins with one byte indicating the number of local
variables it has (between 0 and 15 inclusive).

\sp{2.1} In Versions 1 to 4, that number of 2-byte words follows,
giving initial values for these local variables.  In Versions 5 and
later, the initial values are all zero.

\nsp{3} Execution of instructions begins from the byte after this
header information.  There is no formal `end-marker' for a routine
(it is simply assumed that execution eventually results in a return
taking place).

\nsp{4} In Version 6, there is a ``main'' routine (whose packed address
is stored in the word at |$06| in the header) called when the game
starts up.  It is illegal to return from this routine.

\nsp{5} In all other Versions, the word at |$06| contains the
byte address of the first instruction to execute.  The Z-machine
starts in an environment with no local variables from which, again,
a return is illegal.

\remarks
Note that it is permissible for a routine to be in dynamic memory.
Marnix Klooster suggests this might be used for compiling code at
run time!

In Versions 3 and 4, Inform always stores 0 as the initial values
for local variables.

Inform's ``main'' routine is required not to have local variables
and has to be the first defined routine.  This ensures it is in the
bottom 64K of memory, as it must be (in Versions other than 6).

% ----------------------------------------------------------------------------

\specs{6}{The game state: storage and routine calls}

\sp{1} The ``state of play'' is defined as the following: the contents
of dynamic memory; the contents of the stack; the value of the program
counter (PC), and the ``routine call state'' (that is, the chain of routines
which have called each other in sequence, and the values of their local
variables).  Note that the routine call state, the stack and the PC
must be stored outside the Z-machine memory map, in the interpreter's
private memory.

\sp{1.1} The entire state of play must be stored when the game is saved.

\sp{1.1.1} The format of a saved game file is not specified.

\sp{1.1.2} An internal saved game for ``undo'' purposes (if there is one) is
not part of the state of play.  This is important: if a saved game file also
contained the internal saved game at the time of saving, it would be
impossible to undo the act of restoration.  It also prevents internal
saved games from growing larger and larger as they include their
predecessors.

\sp{1.2} On a ``restore'' or ``undo'' (which restores a game saved into
internal memory), the entire state of play is written back except for one
bit: bit 0 of `Flags 2' in the header, the flag revealing whether the game
is being transcribed to printer.

\sp{1.2.1} Before a ``restore'', an interpreter should check that the
file to be used has been saved from the same game currently being played.
(See remark below.)

\sp{1.2.2} After a ``restore'' or ``undo'', an interpreter should reset
the header values marked |Rst| in the header table of \S 11.  (It should
not be assumed that the game was saved by the same interpreter.)

\sp{1.3} A ``restart'' is similar: the entire state is restored from the
original story file; but the transcription bit is preserved; and the
interpreter should reset the |Rst| parts of the header.

\sp{1.4} In Versions 5 and later, an interpreter unable to save the game
state into internal memory (for ``undo'' purposes) must clear bit 4 of
`Flags 2' in the header.

\nsp{2} Global variables (variable numbers |$10| to |$ff|) are stored
in a table in the Z-machine's dynamic memory, at a byte address given in
word 6 of the header.  The table consists of 240 2-byte words and the
initial values of the global variables are the values initially contained in
the table.  (It is legal for a program to alter the table's contents
directly in play, though not for it to change the table's address.)

\nsp{3} Writing to the stack pointer (variable number |$00|) pushes a
value onto the stack; reading from it pulls a value off.  Stack entries
are 2-byte words as usual.

\sp{3.1} The stack is considered as empty at the start of each routine:
it is illegal to pull values from it unless values have first been pushed
on.

\sp{3.2} The stack is left empty at the end of each routine: when a
return occurs, any values pushed during the routine are thrown away.

\sp{3.3} Stack size has not previously been specified.  The author
proposes the present capacity of |Zip| as a future minimum standard:
let the `usage' of a routine call be 4 plus the number of local
variables it has.  During a game the total of the usages for each
routine in the recursive chain of routines being called, plus the
game's own stack usage, must never reach 1024.

\nsp{4} Routine calls occur in the following circumstances: when one
of the |call...| opcodes is executed; in Versions 4 and later, when
timed keyboard input is being monitored; in Versions 5 and later,
when a sound effect finishes; in Version 6, when the game begins
(to call the ``main'' routine); in Version 6, when a ``newline
interrupt'' occurs.

\sp{4.1} A routine call may have any number of arguments, from 0 to
3 (in Versions 1 to 4) or 0 to 7 (Versions 5 and later).  All
routines return a value (though sometimes this value is thrown away
afterward: for example by opcodes in the form |call_vn*|).

\sp{4.2} Routine calls preserve local variables and the stack
(except when the return value is stored in a local variable or onto
the top of the stack).

\sp{4.3} A routine call to packed address 0 is legal: it does nothing
and returns false (0).  Otherwise it is illegal to call a packed
address where no routine is present.

\sp{4.4} When a routine is called, its local variables are created
with initial values taken from the routine header (Versions 1 to
4) or with initial value 0 (Versions 5 and later).  Next, the
arguments are written into the local variables (argument 1 into
local 1 and so on).

\sp{4.4.1} It is legal for there to be more arguments than local
variables (any spare arguments are thrown away) or for there to
be fewer.

\sp{4.5} The return value of a routine can be any Z-machine number.
Returning `false' means returning 0; returning `true' means
returning 1.

\nsp{5} A ``stack frame'' is an index to the routine call state
(that is, the call-stack of return addresses from routines currently
running, and values of local variables within them).  This index
is a Z-machine number.  The interpreter must be able to produce the
current value and to set a value further down the call-stack than
the current one, effectively throwing away its recent history
(see |catch| and |throw|).

\nsp{6} In Version 6, the Z-machine understands a third kind of stack: a
``user stack'', which is a table of words in dynamic memory.  The first word
in this table always holds the number of spare slots on the stack (so the
initial value is the capacity of the stack).  The Z-machine makes no
check on stack under-flow (i.e., pulling more values than were pushed)
which would over-run the length of the table if the program allowed it
to happen.

\remarks
Most interpreters store the whole of dynamic memory to disc as part of their
saved game files, which can make them as much as 45K or so long.  A player
making a serious attack on a game may end up wasting a whole megabyte, more
than convenient without a hard disc.  Bryan Scattergood's Psion interpreter
ingeniously avoids this by only saving bytes of dynamic memory which are
different from the initial state of the game.

It is unspecified how an interpreter should decide whether a saved game file
belongs to the game currently being played.  It is normal to insist that the
release numbers, serial codes and checksums all match.  The |Pinfocom|
interpreter deliberately checks only the release number, so that saved games
can be exchanged between different editions of `Seastalker' (presumably
compiled to handle the sonarscope differently).

The stack is stored in the interpreter's own memory, not anywhere in the
Z-machine.  The game program has no direct access to the stack memory or
stack pointer; on some implementations the game's main stack is also used to
store the routine call state (i.e. the game stack and the call-stack are the
same) but this need not be true.

The stack size specification guarantees in particular that if the game
itself never uses more than 32 stack entries at once then it can have
a recursive depth of at least 90 routine calls.  The author believes
that old Infocom games will all run with a stack size of 512 words.

Note that the ``state of play'' does not include numerous input/output
settings (the current window, cursor position, splitness or otherwise,
which streams are selected, etc.): neither does it include the state
of the random-number generator.  (Games with elaborate status lines
must redraw them after a restore has taken place.)

|Zip| provides ``undo'', but the |ITF| interpreter currently does not (and
|save_undo| returns 0, unfortunately).  This is probably its greatest
failing.  Some Infocom-written interpreters will only provide ``undo'' to a
game which has bit 4 of `Flags 2' set: but Inform 5.5 doesn't set this bit,
so modern interpreters should be more generous.

% ----------------------------------------------------------------------------

\specs{7}{Output streams and file handling}

\sp{1} At any given time text is being output through a selection of
``output streams" (possibly none, possibly several at once).

\sp{1.1} Two output streams are common to all Versions:
number 1 (the screen) and 2 (the game transcript, usually printed
to a printer or a file).

\sp{1.2} Versions 3 and later supply these and two other output streams,
numbered 3 (Z-machine memory) and 4 (a script file of the player's whole
commands and of individual keypresses as read by |read_char|).

\sp{1.2.1} Output stream 3 writes to a table in dynamic memory.  When the
stream is selected, the table may have any contents (even the initial `size'
word will be ignored by the interpreter).  While the stream is selected, the
table's contents are unspecified (and a game cannot safely read or write
to it).  When the stream is deselected, the initial word of the table holds
the number of characters printed and subsequent bytes hold those characters.
Similarly, in Version 6, the total width of printing (in units) will then be
stored in the word at |$30| in the header.  (It is the programmer's
responsibility to make the table large enough: the interpreter performs no
overflow checking.)

\sp{1.2.2} Output stream 3 is unusual in that, while it is selected, no
text is sent to any other output streams which are selected.  (However,
they remain selected.)

\sp{1.2.2.1} Newlines are written to output stream 3 as ASCII 13.  Any
character 10 codes printed should be converted to 13.

\sp{1.2.3} Output stream 4 is unusual in that, when it is selected,
the only text printed to it is that of the player's commands and
keypresses (as read by |read_char|).  (Each command is written, in
one go, when it has been finished: a command which has been timed-out,
or has been terminated by a code in the terminating character codes
table, is not written.  Mistypes and uses of `delete' are not written.)

\nsp{2} On output streams 1 and 2 (only), text printing may be ``buffered''
in that new-lines are automatically printed to ensure that no word
(of length less than the width of the screen) spreads across two lines.
(This process is sometimes called ``word-wrapping''.)

\sp{2.1} In Versions 1 to 3, buffering is always on.  In Versions 4
and later it is on by default (at the start of a game) and a game can
switch it on or off using the |buffer_mode| opcode.

\sp{2.2} In Version 6, each of the eight windows has its own ``buffering
flag''.  In other Versions, the |buffer_mode| applies
only to the lower window.  Output should never be buffered on
the upper window.

\nsp{3} In Versions 1 and 2, output stream 1 is always selected and
stream 2 can be selected or deselected by the game, by setting or clearing
bit 0 of `Flags 2'.

\nsp{4} In Versions 3 and later, all four output streams can be selected
or deselected using the |output_stream| opcode.  In addition, stream 2
can be selected or deselected by setting or clearing bit 0 of `Flags 2'.

\nsp{5} Character codes in the range 256 to 767 can only be printed on
the screen.  The author encourages interpreter-writers to make it easy
for game designers to modify the interpreter to print suitable substitutes
on the other streams.  (For instance, if 500 represents a Chinese dragon
character, this routine might print ``dragon'' on the other streams.)
Failing this, good practice would be to print a question mark on the
other streams.

\nsp{6} In Versions 5 and later, the Z-machine has the ability to load
and save files (using optional operands with the |save| and |restore|
opcodes).

\sp{6.1} |***| Filenames have the following format (approximately the MS-DOS
8.3 rule): one to eight alphanumeric characters, a full stop and zero to
three alphanumeric characters (the ``file extension'').

\sp{6.1.1} The interpreter must convert all filenames to upper case before
use.  If no full stop is given, ``.AUX'' should be appended.

\sp{6.1.2} Games should avoid the extensions ``.INF'', ``.H'', ``.Z''
followed by a number or ``.SAV'': otherwise they may be in danger of erasing
their own object code, source code or saved game files.

\sp{6.2} |***| Saved files are not associated with any particular session
of a game.  They are not part of the ``state of play''.

\sp{6.3} |***| A game may depend on having up to 32 auxiliary files (with
different names).

\sp{6.4} File-handling errors such as ``disc corrupt'' and ``disc full''
should be reported directly to the player by the interpreter.  The error
``file not found'' should only cause a failure return code from |restore|.

\remarks
The {\sl Inform Designer's Manual} advises games always to switch
buffering off when printing to the upper window.  This is wise since
the |ITF| interpreter does not behave correctly on this point.

An ambiguous point about output stream 4 is whether it should contain
the answers to interpreter questions like ``what file name should your
saved game have?'': it can actually be quite useful to be able to include
such answers in test script files.  (When running a long script, I often
save the game at several places during it, in order to save time in
re-running passages.)

Ideally, an interpreter should be able to write time delays (for timed input)
into stream 4 (i.e., to a script file).  In practice this is formidably
hard to implement.

A typical auxiliary file might be one containing the player's preferred
choices.  This would be created when he first changed any of the default
settings, and loaded (if present) whenever the game started up.

% ----------------------------------------------------------------------------

\specs{8}{The screen model}

\sp{1} Text may be printed in any font of the interpreter's choice,
variable- or fixed-pitch: except that when bit 1 of `Flags 2' in
the header is set, or when the text style has been set to Fixed Pitch,
then a fixed-pitch font must be used.

\sp{1.1} In Versions 5 and later, the height and width of the current
font (in units (see below)) should be written to bytes |$26| and
|$27| of the header, respectively.  The width of a font is defined
as the width of its `0' character.

\sp{1.2} An interpreter should ideally provide 4 fonts, with ID numbers
as follows:
\orm\beginstt
   1: the normal font
   2: a picture font
   3: a character graphics font
   4: a Courier-style font with fixed pitch
\endtt\frm
(In addition, font ID 0 means ``the previous font''.)
Ideally all text styles should be available for each font (for instance,
Courier bold should be obtainable) except that font 3 need only be
available in Roman and Reverse Video.  Each font should provide characters
for character codes 32 to 126 (plus character codes for any accented
characters with codes greater than 127 which are being implemented as single
accented letters on-screen).

\sp{1.3} A game must not use fonts other than 1 unless allowed to by the
interpreter: see the |set_font| opcode for how to give or refuse permission. 
(`Beyond Zork' produces different character graphics according to whether or
not font 3 is available: see \S 16 for the full story.)  This permission
may, at the interpreter's whim, depend on which window is active.

\sp{1.3.1} It is legal for a game to change font at any time,
including halfway through the printing of a word.

\sp{1.4} The specification of the ``picture font'' is unknown
(conjecturally, it was intended to provide pictures before Version
6 was properly developed).  Interpreters need not implement it.

\sp{1.5} The specification of the character graphics font is given
in \S 16.

\sp{1.5.1} In Version 5 (only), an interpreter which cannot provide
the character graphics font should clear bit 3 of `Flags 2' in the
header.

\nsp{2} In Versions 1 to 3, a status line should be printed by the
interpreter, as follows.  In Version 3, it must set bit 4 of
`Flags 1' in the header if it is unable to produce a status line.

\sp{2.1} In Versions 1 and 2, all games are ``score games''.  In
Version 3, if bit 1 of `Flags 1' is set then the game is a ``score game'';
otherwise, a ``time game''.

\sp{2.2} The short name of the object whose number is in the first global
variable should be printed on the left hand side of the line.

\sp{2.2.1} Whenever the status line is being printed the first global
must contain a valid object number.  (It would be useful if interpreters
could protect themselves in case the game accidentally violates this
requirement.)

\sp{2.2.2} If the object's short name exceeds the available room on
the status line, the author suggests that an interpreter should break
it at the last space and append an ellipsis ``...''.  There is no
guaranteed maximum length for location names but an interpreter should
expect names of length up to at least 49 characters.

\sp{2.3} If there is room, the right hand side of the status line should
display:

\sp{2.3.1} For ``score games'': the score and number of turns, held in
the values of the second and third global variables respectively.  The
score may be assumed to be in the range $-99$ to $999$ inclusive, and
the turn number in the range $0$ to $9999$.

\sp{2.3.2} For ``time games'': the time, in the form |hours:minutes| (held
in the second and third globals).  The time may be given on a 24-hour clock
or the number of hours may be reduced modulo 12 (but if so, ``AM'' or ``PM''
should be appended).  Either way the player should be able to see the
difference between 4am and 4pm, for example.  The hours global may be
assumed to be in the range 0 to 23 and the minutes global in the range
0 to 59.

\sp{2.4} The status line is updated in exactly two circumstances: when
a |show_status| opcode is executed, and just before the keyboard is
read by |read|.  (It is not displayed when the game begins.)

\nsp{3} Under Versions 5 and later, text printing has a current
foreground and background colour.  (In Version 6, each window has its
own pair.)

\sp{3.1} The following codes are used to refer to colours:
\orm\beginstt
    -1 =� the colour of the pixel under the mouse arrow (if any)
    0  =  the current setting of this colour
    1  =  the default setting of this colour
    2  =  black   3 = red       4 = green    5 = yellow
    6  =  blue    7 = magenta   8 = cyan     9 = white
\endtt\frm
(These are loosely based on the IBM PC colour-scheme.)

\sp{3.2} If the interpreter cannot produce colours, it should clear
bit 0 of `Flags 1' in the header.

\sp{3.3} If the interpreter can produce colours, it should set bit
0 of `Flags 1' in the header, and write its default background
and foreground colours into bytes |$2c| and |$2d| of the header.

\sp{3.4} If a game wishes to use colours, it should have bit 6 in
`Flags 2' set in its story file.  (However, an interpreter should not
rule out the use of colours just because this has not been done.)

\nsp{4} The screen should ideally be at least 60 characters wide by 14 lines
deep.  (Old Apple II interpreters had a 40 character width and some modern
laptop ones have a 9 line height, but implementors should seek to avoid
these extremes if possible.)  The interpreter may change the exact
dimensions whenever it likes but must write the current height (in lines)
and width (in characters) into bytes |$20| and |$21| in the header.

\sp{4.1} The interpreter should use the screen height for calculating
when to pause and print ``[MORE]''.  A screen height of 255 lines means
``infinite height'', in which case the interpreter should never stop
printing for a ``[MORE]'' prompt.  (In case, say, the screen is actually
a teletype printer, or has very good ``scrollback''.)

\sp{4.2} Screen dimensions are measured in notional ``units''.  In
Versions 1 to 4, one unit is simply the height or width of one character.
In Version 5 and later, the interpreter is free to implement units as
anything from character sizes down to individual pixels.

\sp{4.3} In Version 5 and later, the screen's width and height in units
should be written to the words at |$22| and |$24|.

\nsp{5} The screen model for Versions 1 and 2 is as follows:

\sp{5.1} The screen can only be printed to (like a teletype) and there
is no control of the cursor.

\sp{5.2} At the start of a game, the screen should be cleared and the text
cursor placed at the bottom left (so that text scrolls upwards as the game
gets under way).

\nsp{6} The screen model for Version 3 is as follows:

\sp{6.1} The screen is divided into a lower and an upper window and at any
given time one of these is selected.  (Initially it is the lower
window.)  The game uses the |set_window| opcode to select one of the
two.  Each window has its own cursor position at which text is
printed.  Operations in the upper window do not move the cursor of the
lower.  Whenever the upper window is selected, its cursor position is
reset to the top left.  Selecting, or re-sizing, the upper window does
not change the screen's appearance.

\sp{6.1.1} The upper window has variable height (of $n$ lines) and the
same width as the screen.  This should be displayed on the $n$ lines of
the screen below the top one (which continues to hold the status line).
Initially the upper window has
height 0.  When the lower window is selected, the game can split off
an upper window of any chosen size by using the |split_window| opcode.

\sp{6.1.1.1} Printing onto the upper window overlays whatever text is
already there.  Printing is normally buffered (unless the game has turned
this off), just as in the lower window.

\sp{6.1.2} An interpreter need not provide the upper window at all.  If
it is going to do so, it should set bit 5 of `Flags 1' in the header to
signal this to the game.  It is only legal for a game to use
|set_window| or |split_window| if this bit has been set.

\sp{6.1.3} Following a ``restore'' of the game, the interpreter should
automatically collapse the upper window to size 0.

\sp{6.2} When text reaches the bottom right of the lower window, it
should be scrolled upwards.  The upper window should never be scrolled:
it is legal for a character to be printed on the bottom right position
of the upper window (but the position of the cursor after this operation
is undefined: the author suggests that it stay put).

\sp{6.3} At the start of a game, the screen should be cleared and the text
cursor placed at the bottom left (so that text scrolls upwards as the game
gets under way).

\nsp{7} The screen model for Versions 4 and later, except Version 6,
is as follows:

\sp{7.1} Text can be printed in five different styles (modelled on the
VT100 design of terminal).  These are: Roman (the default), Bold, Italic,
Reverse Video (usually printed with foreground and background colours
reversed) and Fixed Pitch.  The specification does not require the
interpreter to be able to display more than one of these at once (e.g. to
combine italic and bold), and most interpreters can't.  If the interpreter
is going to allow certain combinations, then note that changing back to
Roman should turn off all the text styles currently active.

\sp{7.1.1} An interpreter need not provide Bold or Italic (even for font 1)
and is free to interpret them broadly.  (For example, rendering bold-face by
changing the colour, or rendering italic with underlining.)

\sp{7.1.2} It is legal to change text style at any point, including in
the middle of a word being printed.

\sp{7.2} There are two ``windows'', called ``upper'' and ``lower'': at
any given time one of these two is selected.  (Initially it is the lower
window.)  The game uses the |set_window| opcode to select one of the
two.  Each window has its own cursor position at which text is
printed.  Operations in the upper window do not move the cursor of the
lower.  Whenever the upper window is selected, its cursor position is
reset to the top left.

\sp{7.2.1} The upper window has variable height (of $n$ lines) and the
same width as the screen.  (It is usual for interpreters to print the
upper window on the top $n$ lines of the screen, overlaying any text
which is already there, having been printed in the lower window some
time ago.)  Initially the upper window has height 0.  When the lower
window is selected, the game can split off an upper window of any
chosen size by using the |split_window| opcode.

\sp{7.2.1.1} It is unclear exactly what |split_window| should do if
the upper window is currently selected.  The author suggests that
it should work as usual, leaving the cursor where it is if the
cursor is still inside the new upper window, and otherwise moving
the cursor back to the top left.  (This is analogous to the Version 6
practice.)

\sp{7.2.2} In Version 4, the lower window's cursor is always on
the bottom screen line.  In Version 5 it can be at any line which is
not underneath the upper window.  If a split takes place which would
cause the upper window to swallow the lower window's cursor position,
the interpreter should move the lower window's cursor down to the
line just below the upper window's new size.

\sp{7.2.3} When the upper window is selected, its cursor position
can be moved with |set_cursor|.  This position is given in characters
in the form (row, column), with $(1,1)$ at the top left.  The opcode
has no effect when the lower window is selected.  It is illegal
to move the cursor outside the current size of the upper window.

\sp{7.2.4} An interpreter should use a fixed-pitch font when printing on
the upper window.

\sp{7.2.5} In Version 4, text buffering should work in the upper window
exactly as it does in the lower one (i.e., it must be turned off by
the game if it is not required).  In Versions 5 and later, text buffering
is never active in the upper window (even if a game begins printing there
without having turned it off).

\sp{7.3} Clearing regions of the screen:

\sp{7.3.1} When text reaches the bottom right of the lower window, it
should be scrolled upwards.  (When the text style is Reverse Video
the new blank line should {\bf not} have reversed colours.)  The upper
window should never be scrolled: it is legal for a character to be
printed on the bottom right position of the upper window (but the
position of the cursor after this operation is undefined: the author
suggests that it stay put).

\sp{7.3.2} Using the opcode |erase_window|, the specified window
can be cleared to background colour.  (Even if the text style is Reverse
Video the new blank space should not have reversed colours.)

\sp{7.3.2.1} In Versions 5 and later, the cursor for the window being erased
should be moved to the top left.  In Version 4, the lower window's cursor
moves to its bottom left, while the upper window's cursor moves to top left.

\sp{7.3.3} Erasing window $-1$ clears the whole screen, collapses the
upper window to height 0 and moves the cursor of the lower screen
to bottom left (in Version 4) or top left (in Versions 5 and
later).  The same operation should happen at the start of a game.

\sp{7.3.4} Using |erase_line| in the upper window should erase
the current line from the cursor position to the right-hand edge,
clearing it to background colour.  (Even if the text style is
Reverse Video the new blank space should not have reversed colours.)

\nsp{8} The screen model for Version 6 is as follows:

\sp{8.1} The display is an array of pixels.  Coordinates are usually
given (in units) in the form $(y,x)$, with $(1,1)$ in the top left.

\sp{8.2} If the interpreter thinks the status line should be redrawn
(e.g. because a menu window has been clicked over it), it may set bit
2 of `Flags 2'.  The game is expected to notice, take action and clear
the bit.  (However, a more efficient interpreter would cache
the status line and handle redraws itself.)

\sp{8.3} There are eight ``windows'', numbered 0 to 7.  The code $-3$
is used as a window number to mean ``the currently selected window''.
This selection can be changed with the |set_window| opcode.
Windows are invisible and usually lie on top of each other.  When
something is printed in a window, it appears on the screen, but
subsequent movements of the window do not move what was printed and
there is no sense in which characters `belong' to any particular
window once printed.  Each window has a position (in units), a size
(in units), a cursor position within it (in units, relative to its
own origin), a number of flags called ``attributes'' and a number
of variables called ``properties''.

\sp{8.3.1} There are four attributes, numbered as follows:
\orm\beginstt
    1: character wrapping
    2: scrolling
    3: text copied to output stream 2 (the transcript, if selected)
    4: buffered printing
\endtt\frm
Each can be turned on or off, using the |window_style| opcode.

\sp{8.3.1.1} Character wrapping takes place (if set) when printing
a character would push beyond the right-hand edge of the window:
if set, then the character is printed on the left of the next line.
If it is clear, then text is printed along the line but clipped
to the window size.

\sp{8.3.2} There are 16 properties, numbered as follows:
\orm\beginstt
    0  y coordinate    6   left margin size            12  font number
    1  x coordinate    7   right margin size           13  font size
    2  y size          8   newline interrupt routine   14  attributes
    3  x size          9   interrupt countdown         15  line count
    4  y cursor        10  text style
    5  x cursor        11  colour data
\endtt\frm
Each property is a standard Z-machine number and is readable
with |get_wind_prop| and writeable with |put_wind_prop|.  However,
a game should only use |put_wind_prop| to set the newline
interrupt routine and interrupt countdown: everything else is
either set by the interpreter (such as the line count) or
set using specialised opcodes (such as |set_font|).

\sp{8.3.2.1} If a window has character wrapping, then text is
clipped to stay inside the left and right margins.  After a
new-line, the cursor moves to the left margin on the next line.
Margins can be set with |set_margins| but this should only be
done just after a newline or just after the window has been
selected.  (These values are margin sizes in pixels, and are by
default 0.)

\sp{8.3.2.2} If the interrupt countdown is set to a non-zero value
(which by default it is not), then the line count is decremented on each
new-line, and when it hits zero the routine whose packed address is stored
in the ``newline interrupt routine'' property is called before text printing
resumes.  (This routine may, for example, meddle with margins to roll text
around a crinkly-shaped picture.)  The interrupt routine should not attempt
to print anything.

\sp{8.3.2.3} The text style is set just as in Version 4, using
|set_text_style| (which sets that for the current window).  The
property holds the operand of that instruction (e.g. 4 for italic).

\sp{8.3.2.4} The foreground colour is stored in the upper byte of the
colour data property, the background colour in the lower byte.

\sp{8.3.2.5} The font height (in pixels) is stored in the upper byte of the
font size property, the font width (in pixels) in the lower byte.

\sp{8.3.2.6} The interpreter may use the line count to see when it
should print ``[MORE]''.

\sp{8.3.3} All eight windows begin at $(1,1)$.  Window 0 occupies the
whole screen and is initially selected.
Window 1 is as wide as the screen but has zero height.  Windows 2 to 7
have zero width and height.  All eight windows begin with buffered
printing on, and the other attributes off.

\sp{8.3.4} A window can be moved with |move_window| and resized with
|window_size|.  If the window size is reduced so that its cursor lies
outside it, the cursor should be reset to the left margin on the top
line.

\sp{8.3.5} Each window remembers its own cursor position (relative
to its own coordinates, so that the position $(1,1)$ is at its top
left).  These can
be changed using |set_cursor| (and it is legal to move the cursor
for an unselected window).  It is illegal to move the cursor outside
the current window.

\sp{8.3.6} Each window can be scrolled vertically (up or down) any
number of pixels, using the |scroll_window| opcode.

\sp{8.4} To some extent windows 0 and 1 mimic the behaviour of the
lower and upper windows in the Version 4 screen model:

\sp{8.4.1} The
|split_screen| opcode tiles windows 0 and 1 so that window 1 has
the given height and is placed at the top left, while window 0 is
moved to be just below it and has its height shortened by the
height of window 1.  (If this makes a negative amount, the height
becomes 0.)  Finally, window 0 is selected.

\sp{8.4.2} An ``unsplit'' (that is, a |split_screen 0|) takes place
when the entire screen is cleared with |erase_window -1|, if a
``split'' has previously occurred (meaning that windows 0 and 1
have been set up as above).

\sp{8.5} Screen clearing operations:

\sp{8.5.1} Erasing a picture is like drawing it (see below), except
that the space where it would appear is painted over with background
colour instead.

\sp{8.5.2} The current line can be erased using |erase_line|, either
all the way to the right margin or by any positive number of pixels in
that direction.  The space is painted over with background colour
(even if the current text style is Reverse Video).

\sp{8.5.3} Each window can be erased using |erase_window|, erasing to
background colour (even if the current text style is Reverse Video).

\sp{8.5.3.1} Erasing window number -1 erases the entire screen
and unsplits windows 0 and 1 (see above).

\sp{8.5.3.2} Erasing window -2 erases the entire screen (without
changing any window attributes or cursor positions).

\sp{8.6} Pictures may accompany the game.  They are not stored in the
story file (or the Z-machine) itself, and the interpreter is simply
expected to know where to find them.  Infocom supplied files of
pictures in different formats on different machines.  The exact format of
such files is not specified here.

\sp{8.6.1} Pictures are numbered from 1 upwards (not necessarily
contiguously).  They can be ``drawn'' or ``erased'' (using |draw_picture|
and |erase_picture|).  Before attempting to do so, a game may ask the
interpreter about the picture (using |picture_data|): this allows the
interpreter to signal that the picture in question is unavailable,
or to specify its height and width.

\sp{8.6.2} The game may, if it wishes, use the |picture_table| opcode
to give the interpreter advance warning that a group of pictures will
soon be needed (for instance, a collection of icons making up a control
panel).  The interpreter may want to load these pictures off disc and
into a memory cache.

\remarks
See \S 16 for comment on how `Beyond Zork' uses fonts.

Some interpreters print the status line when they begin running a Version
3 game, but this is incorrect.  (It means that a small game printing text
and then quitting cannot be run unless it includes an object.)  The author's
preferred status line formats are:
\beginstt
Hall of Mists                                 80/733
Lincoln Memorial                              12:03 PM
\endtt
Thus the score/turns block always fits in $3+1+4=8$ characters and the
time in $2+1+2+1+2=8$ characters.  (Games needing more exotic time lines,
for example, should not be written in Version 3.)

The only existing Version 3 game to use an upper window is `Seastalker'
(for its sonarscope display).

Some ports of |ITF| apply buffering (i.e. word-wrapping) and scrolling to
the upper window, with unfortunate consequences.  This is why
the standard Inform status line is one character short of the width
of the screen.

The original Infocom files seldom use |erase_window|, except with window
$-1$ (for instance `Trinity' only uses it in this form).  |ITF| does not
implement it in any other case.

The Version 5 re-releases of older games make use of consecutive
|set_text_style| instructions to attempt to combine boldface reverse video
(in the hints system).

None of Infocom's Version 4 or 5 files use |erase_line| at all, and |ITF|
implements it badly (with unpredictable behaviour in Reverse Video text
style).  (It's interesting to note that the Version-5 edition of `Zork I'
- one of the earliest Version 5 files -- blanks out lines by looking up
the screen width and printing that many spaces.)

Note that a minor bug in |Zip| writes bytes |$22| to |$25| in the
header as four values, giving the screen dimensions in the form left,
right, top, bottom: provided units are characters (i.e. provided the
font width and height are both 1) then since ``left'' and ``top''
are both 0, this bug has no effect.

Some details of the known IBM graphics files are given in Paul David
Doherty's ``Infocom Fact Sheet''.  See also Mark Howell's program
``pix2gif'', which extracts pictures to GIF files.  (This is one of
his ``Infocom toolkit'' programs.)

% ----------------------------------------------------------------------------

\specs{9}{Sound effects}

\sp{1} Some games, from Version 3 onward, have sound effects attached.
These are not stored in the story files (or the Z-machine) itself,
and the interpreter is simply expected to know where to find them.
Infocom implemented sound effects differently on different machines.

\sp{1.1} In Version 6, the interpreter should set bit 5 of `Flags 1'
if it can provide sound effects.

\sp{1.2} In Version 5 and later, a game should have bit 7 of `Flags 2'
set in its story file if it wants to use sound effects.  The interpreter
should then clear this bit if it cannot oblige.

\nsp{2} Sound effects are numbered upwards from 1.  Number 1 is a
high-pitched beep, number 2 a low-pitched one and effects from 3 upward
are supplied by the interpreter somehow for the particular game in
question.

\nsp{3} A sound effect can be played at any volume level from 1 to 8 (8
being loudest of these).  The volume level $-1$ should be implemented as
``loudest possible''.

\nsp{4} Sound effects take place in the background, while normal operation
of the Z-machine is going on.  Control is via the |sound_effect| opcode,
allowing the game to prepare, start, stop or finish with an effect.

\sp{4.1} The game may (but need not) ``prepare'' a sound effect before
use.  This would indicate to the interpreter that the game intends
to use the effect soon: an interpreter might act on this information by
loading the sampled sound off disc and into a memory cache.

\sp{4.2} A sound effect can then be ``stopped'' or ``started''.  Only one
sound effect is playing at any given time, and starting a new sound effect
automatically stops any current one.

\sp{4.3} In Versions 5 and later, a sound effect may repeat any specified
number of times, or repeat forever (until stopped).

\sp{4.4} Eventually, though, if it has not been stopped, it may end by itself.
A routine (specified at start time) can then be called.  The intention is that
this routine may implement effects such as fading in and out, by replaying
the sound effect at a different volume.  (A game should not place any important
code in such a routine.)

\sp{4.5} The game should explicitly ``finish with'' any sound effect which is
not likely to occur again for a while: the interpreter can then throw it out
of memory.

\remarks
The safest way an Inform program can try to produce a bleep is by
executing |@sound_effect 1|.  Some ports of |Zip| believe that the
first operand of this is the number of bleeps to make (so that
|@sound_effect 2| bleeps twice), but this is incorrect.

Only two Infocom games provided sound effects: `The Lurking Horror'
and `Sherlock'.  Their story files only contain the following usages of
|sound_effect|:
\beginstt
  sound_effect 1
  sound_effect 2
  sound_effect number 2 volume                   (in TLH)
  sound_effect number 2 volume/repeats function  (in Sherlock)
  sound_effect 0 3
  sound_effect 0 4
\endtt

The format of Infocom's shipped sound effects files has been documented by
Stefan Jokisch and his notes are available from |ftp.gmd.de|.

% ----------------------------------------------------------------------------

\specs{10}{Input streams and devices}

\sp{1} In Versions 1 and 2, the player's commands can only be
drawn from the keyboard.

\nsp{2} In Versions 3 and later, the player's keypresses are drawn
from the current ``input stream''.  There are two input streams:
numbered 0 (the keyboard) and 1 (a file containing commands).
Other inputs (mouse clicks or menu selections), if available,
are also implemented as keypresses (see below).

\sp{2.1} The format of a file containing commands must be the same as
that written in output stream 4.

\sp{2.2} The game can change the current input stream itself, using
the opcode |input_stream|.  It has no way of finding out which input
stream is currently in use.  An interpreter is free to change the
input stream whenever it likes (e.g. at the player's request) or,
indeed, to run the entire game under input stream 1 (for testing
purposes).

\sp{2.3} When input stream 1 is first selected, the interpreter may
use any method of choosing a file name for the file of commands.  (Good
practice is to use the same conventions as when choosing a filename
for output to stream 4.)

\sp{2.4} When the the current stream is stream 1, the interpreter
should not hold up long passages of text (by printing ``[MORE]''
and waiting for a keypress, for instance).

\nsp{3} Mouse support is optional but can be provided in Versions 5 and
later.

\sp{3.1} In a game which wishes to use the mouse, bit 5 of `Flags 2'
in the header should be set in the story file, and word |$36| of the
header should be the byte address of the mouse data table in dynamic
memory.

\sp{3.1.1} If the interpreter cannot offer mouse support, then it
should clear bit 5 of `Flags 2' to signal this to the game.

\sp{3.2} The mouse data table has the format:
\orm\beginstt
   Word 0:  Length of the table (in words)
   Word 1:  Mouse x coordinate
   Word 2:  Mouse y coordinate
\endtt\frm
(The table length is usually 2.)  These coordinates should be
updated regularly by the interpreter.

\sp{3.3} The mouse is presumed to have between 0 and 16 buttons.
The state of these buttons can be read by the |read_mouse| opcode
in Version 6.  Otherwise, mouse clicks are treated as keyboard
input codes (see below).

\sp{3.4} In Version 6, the mouse can either be free or constrained
to one of the 8 windows: if so, clicks outside the `mouse window'
must be ignored, and the interpreter is at liberty to confine the
mouse's movement to the boundary of its window.

\nsp{4} Menu support can optionally be provided in Version 6.

\sp{4.1} In a game which wishes to use menus, bit 8 of `Flags 2'
in the header should be set in the story file.

\sp{4.1.1} If the interpreter cannot offer menu support, then it
should clear bit 8 of `Flags 2' to signal this to the game.

\sp{4.2} Menus are numbered from 0 upwards.  0, 1 and 2 are reserved for
the interpreter to manage (this system has only been implemented on
the Macintosh, wherein 0 is the Apple menu, 1 the File menu and 2 the
Edit menu).  Menus numbered 3 and upwards can be created or removed with
the |make_menu| opcode.

\sp{4.3} Menu selection is reported to the game as a keypress
(see below).  Details of what selection has been made are read with
|read_mouse|.

\nsp{5} Whole commands are read from the input stream using the |read|
opcode.  (Note that this has two different internal names in Inform,
|sread| for Versions 1 to 4 and |aread| subsequently.)

\sp{5.1} In Versions 1 to 3, the interpreter must redisplay the status
line before it begins accepting input.

\sp{5.2} Commands are normally terminated by a new-line (a carriage
return or a line feed as appropriate for the machine's keyboard or
file format).

\sp{5.2.1} In Versions 5 and later, the game may provide a
``terminating characters table'' by giving its byte address in
the word at |$2e| in the header.  This table is a zero-terminated
list of input character codes which cause |aread| to finish the
command (in addition to new-line).  Only function key codes are
permitted: these are defined as those between 129 and 154
inclusive, together with 252, 253 and 254.  The special value
255 means ``any function key code is terminating''.

\sp{5.3} |***| In Versions 4 and later, an interpreter should ideally
be able to time input and to call a (game) routine at periodic
intervals: see the |aread| opcode.  If it is able to do this, it
should set bit 7 of `Flags 1' in the header.

\nsp{6} In Versions 4 and later, individual characters can be read
from the current input stream, using |read_char|.  Again, the interpreter
should ideally be able to time input and to call a (game) routine at
periodic intervals.  If it is able to do this, it should set bit 7 of `Flags
1' in the header.

\nsp{7} For input purposes the character set is as follows:
\orm\beginstt
 0-9       ----
 10        New-line   (ends input of a command)
 11-12     ----
 13        New-line   (ends input of a command)
 14-26     ----
 27        Escape
 28-31     ----
 32-126    Standard ASCII           (see 3.4.3)
 127-128   ----
 129-154   Function key codes       (see below)
 155-251   Accented letter codes    (see below)
 252-254   Function key codes       (see below)
 255-      ----
\endtt\frm
The codes marked |----| should never be read.  (Of course an
interpreter may well want to use other ASCII codes for its own
line-editor when the player is typing a command: 127 for ``delete'',
for instance.  The table means only that these codes should not
be passed to the game.)  Note that an interpreter can return
either 10 or 13 as ``new-line''.  (The recommended choice is
10.)

\sp{7.1} The ``escape'' code is optional: an interpreter need not
provide an escape key.  (The Inform library clears and quits menus
if Escape is pressed.)

\sp{7.2} The first block of function key codes is as follows:
\orm\beginstt
129: cursor up  130: cursor down  131: cursor left  132: cursor right
133: f1         134: f2           ....              144: f12
145: keypad 0   146: keypad 1     ....              154: keypad 9
\endtt\frm

\sp{7.3} The input codes 155 to 251 refer to European accented
letters: see the table in \S 3.4.4.

\sp{7.4} In Version 6, mouse clicks and menu selections are reported
as the function key codes:
\orm\beginstt
252: menu click   253: mouse double-click   254: mouse single-click
\endtt\frm
In Versions 5 and later (except 6), menus are unavailable, and it is
legal for an interpreter to translate both forms of mouse-click as
code 254.  This is the recommended practice but a game should not
depend on it.

\sp{7.5} All the codes not marked as |----| should be passed to
|read_char|.  Function key codes and the code for ``escape'' should
not be entered by |read| into the input buffer (they have no
specified appearance on screen), but accented letter codes should.

\remarks
Menus in `Beyond Zork' define cursor up and cursor down as terminating
characters, and make use of |read| in the upper window.

Ideally, an interpreter should be able to read time delays (for timed input)
from stream 1 (i.e., from a script file).  In practice this is formidably
hard to implement.

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.

% ----------------------------------------------------------------------------

\specs{11}{The format of the header}

\sp{1} The header table summarises those locations in the Z-machine's
header which an interpreter must deal with.  (For much fuller details,
see Appendix A.)  ``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.

\pageinsert
\smallskip\hrule\smallskip
\beginlines
| Hex  V  Dyn Int Rst  Contents|
\endlines\smallskip\hrule\smallskip\beginlines
|  0   1               Version number (1 to 6)|
|  1   3               Flags 1:|
|      .3                Bit 1    Status line type: 0=score/turns, 1=hours:mins|
|      .3      *   *         4    Status line not available?|
|      .3      *   *         5    Screen-splitting available?|
|      .3      *   *         6    Is a variable-pitch font the default?|
|      4               Flags 1:|
|      .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 (single ASCII character)|
\endlines\smallskip\hrule\smallskip
\noindent Some early Version 3 files do not contain length and checksum
data, hence the notation |3+|.
\vfill\endinsert

\topinsert
\smallskip\hrule\beginlines
| Hex  V  Dyn Int Rst  Contents|
\endlines\smallskip\hrule\smallskip\beginlines
| 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 height in units|
| 27   5       *   *   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               Character set table address (bytes), or 0 for default|
| 36   5               Mouse data table address (bytes)|
\endlines\smallskip\hrule\bigskip
\endinsert

\sp{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.

\sp{1.2} The state of the transcription bit (bit 0 of Flags 2) is only
changed by the game (see \S 7.3, \S 7.4), but the interpreter ensures that
its value survives a restart or restore.

\sp{1.3} Infocom used the interpreter numbers:
\orm\beginstt
   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
\endtt\frm
(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.  (The main consideration is that the behaviour of `Beyond Zork'
actually depends on the interpreter number.)

\sp{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.

\sp{1.5} |***| If an interpreter obeys Revision |n.m| of this document {\sl
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.

\sp{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.

\remarks
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.

% ----------------------------------------------------------------------------

\specs{12}{The object table}

\sp{1} The object table is held in dynamic memory and its byte address
is stored in the word at |$0a| in the header.  (Recall that objects
have flags attached called attributes, numbered from 0 upward, and
variables attached called properties, numbered from 1 upward.  An
object need not provide every property.)

\nsp{2} The table begins with a block known as the property defaults table.
This contains 31 words in Versions 1 to 3 and 63 in Versions 4 and later.
When the game attempts to read the value of property $n$ for an object
which does not provide property $n$, the $n$-th entry in this table
is the resulting value.

\nsp{3} Next is the object tree.  Objects are numbered consecutively from
1 upward, with object number 0 being used to mean ``nothing'' (though
there is formally no such object).  The table consists of a list of
entries, one for each object.

\sp{3.1} In Versions 1 to 3, there are at most 255 objects, each having
a 9-byte entry as follows:
\orm\beginstt
   <the 32 attribute flags>   <parent>  <sibling>  <child>  <properties>
   ---32 bits in 4 bytes---   ---3 bytes------------------  ---2 bytes--
\endtt\frm
|parent|, |sibling| and |child| must all hold valid object numbers.
The |properties| pointer is the byte address of the list of
properties attached to the object.  Attributes 0 to 31 are flags
(at any given time, they are either on (1) or off (0)) and are stored topmost
bit first: e.g., attribute 0 is stored in bit 7 of the first byte,
attribute 31 is stored in bit 0 of the fourth.

\sp{3.2} In Version 4 and later, there are at most 65535 objects, each
having a 14-byte entry as follows:
\orm\beginstt
   <the 48 attribute flags>   <parent>  <sibling>  <child>  <properties>
   ---48 bits in 6 bytes---   ---3 words, i.e. 6 bytes----  ---2 bytes--
\endtt\frm

\nsp{4} Each object has its own property table.  Each of these can be
anywhere in dynamic memory (indeed, a game can legally change an object's
properties table address in play, provided the new address points to
another valid properties table).

\sp{4.1} In Versions 1 to 3, a property table has header:
\orm\beginstt
  <text-length>   <text of short name of object>
  -----byte----   --some even number of bytes---
\endtt\frm
where the |text-length| is the number of 2-byte words making up the text,
which is stored in the usual format.  (This means that an object's short
name is limited to 765 Z-characters.)  After the header, the properties
are listed in descending numerical order.  (This order is essential and
is not a matter of convention.)  Each property is stored as a block
\orm\beginstt
  <size byte>   <the actual property data>
                ---between 1 and 8 bytes--
\endtt\frm
where the |size byte| is arranged as 32 times the number of data bytes
minus one, plus the property number.  A property list is terminated by
a size byte of 0.  (It is otherwise illegal for a size byte to be a
multiple of 32.)

\sp{4.2} In Versions 4 and later, a property block instead has the form
\orm\beginstt
  <size and number>     <the actual property data>
  --1 or 2 bytes---     --between 1 and 64 bytes--
\endtt\frm
The property number occupies the bottom 6 bits of the first size byte.

\sp{4.2.1} If the top bit of the size byte is set, then there is a
second size byte.  The bottom six bits contain the property data
length (counting in bytes), minus 1, and the top two bits must be
|$$10|.

\sp{4.2.2} Otherwise, if bit 6 of the size byte is set then the
length is 2, and if it is clear then the length is 1.

\sp{5} It is the game's responsibility to keep the object tree
well-founded: the interpreter is not required to check.
``Well-founded'' means the following:
\item{(a)} An object with a sibling also has a parent.
\item{(b)} An object is the parent of exactly those objects
in the sibling list of its child.
\item{(c)} Each object can be given a level $n$, such that
parentless objects have level $0$ and all children of a level
$n$ object have level $n+1$.

\remarks
The largest valid object number is not directly stored anywhere
in the Z-machine.  Utility programs like ``Infodump'' deduce this
number by assuming that, initially, the object entries end where
the first property table begins.

The reason why the second property size byte needs to have top bits set
to |$$10| is that the size field must be parsable either
forwards or backwards -- the Z-machine needs to be able to reconstruct the
length of a property given only the address of the first byte of its data.
(There are very many (e.g. 2000) property entries in a story file, so
optimising size into one byte most of the time is worthwhile.)

In fact only the top bit of the second byte needs to be set, so it
would be extremely easy to modify an interpreter to allow up to 128
bytes of property data.  Infocom seem not to have noticed, or not to
have needed this.

Inform can only construct well-founded object trees as the initial game
state, but it is easy to compile sequences of code like ``move red box to
blue box'' followed by ``move blue box to red box'' which leave the object
tree in an ill-founded state.  (The Inform library protects the standard
object-movement verbs against this.)

% ----------------------------------------------------------------------------

\specs{13}{The dictionary and lexical analysis}

\sp{1} The dictionary table is held in static memory and its byte address
is stored in the word at |$08| in the header.

\nsp{2} The table begins with a short header:
\orm\beginstt
  n    <list of keyboard input codes>  entry-length  number-of-entries
 byte  ------n bytes-----------------      byte         2-byte word
\endtt\frm
The keyboard input codes are ``word-separators'': typically (and under
Inform mandatorily) these are the ASCII codes for full stop, comma and
double-quote.  Note that a space character (32) should never be a
word-separator.  The ``entry length'' is the length of each word's
entry in the dictionary table.  (It must be at least 4 in Versions
1 to 3, and at least 6 in later Versions.)

\sp{2.1} Note that control codes such as the ASCII for ``tab'' are
never given in the word-separators table: they aren't legal keyboard
input codes (an interpreter might sensibly convert a tab to a space).

\nsp{3} In Versions 1 to 3, each word has an entry in the form
\orm\beginstt
  <encoded text of word>      <bytes of data>
  ------- 4 bytes ------   (entry length-4) bytes
\endtt\frm
The interpreter ignores the bytes of data (presumably the game's parser will
use them).  The encoded text contains 6 Z-characters (it is always padded
out with Z-character 5's to make up 4 bytes: see ``How strings are
encoded'').  The text may include spaces or other word-separators
(though, if so, the interpreter will never match any text to the
dictionary word in question: surprisingly, this can be useful and is
a trick used in Inform 5/12).

\nsp{4} In Versions 4 and later, the encoded text has 6 bytes and
always contains 9 Z-characters.

\nsp{5} The word entries follow immediately after the dictionary header
and must be given in numerical order of the encoded text (when the encoded
text is regarded as a 32 or 48-bit binary number with most-significant
byte first).  It must not contain two entries with the same encoded text.

\nsp{6} Lexical analysis takes place in two circumstances: on request
of a |tokenise| opcode (in which case it can use any dictionary table
it likes, in the format above) and during acceptance of a game command
(in which case the standard dictionary is used).

\sp{6.1} First, the text is broken up into words.  Spaces divide up
words and are otherwise ignored.  Word separators also divide words,
but each one of them is considered a word in its own right.  Thus,
the erratically-spaced text ``fred,go  fishing'' is divided into four
words:
\orm\beginstt
fred / , / go / fishing
\endtt\frm

\sp{6.2} Each word is then encoded as a Z-machine string in
dictionary form, and searched for in the dictionary.

\sp{6.3} A ``parse table'' is then written, recording the number of
words, the length and position of each word and the dictionary
address of each word which is recognised.  For the format, see the
|sread| opcode.

\remarks
Usually (under Inform, mandatorily) there are three bytes of data
in the word entries, so that dictionary entry lengths are 7 and 9
in the early and late Z-machine, respectively.

It is essential that dictionary entries are in numerical order of the
bytes of encrypted text so that interpreters can search the dictionary
efficiently (e.g. by a binary-chop algorithm).  Because the letters in
A0 are in alphabetical order, because the bits are ordered in the right
way and because the pad character 5 is less than the values for the
letters, the numerical ordering corresponds to normal English alphabetical
order for ordinary words.  (For instance ``an'' comes before
``anaconda''.)

The Infocom games do contain words whose initial
character is not a letter (words such as ``\#record'').

% ----------------------------------------------------------------------------

\specs{14}{Complete table of opcodes}

\sp{1} This table contains all 117 opcodes and, taken with the dictionary
in \S 15, describes exactly what each should do.  In addition, it lists which
opcodes are actually used in the known Infocom story files, and documents the
Inform assembly language syntax.

\subtitle{Reading the opcode tables}

The two columns ``St" and ``Br" (store and branch) mark whether an
instruction stores a result in a variable, and whether it must provide a
label to jump to, respectively.

The ``Opcode" is written |TYPE:Decimal| where the |TYPE| is the operand
count (2OP, 1OP, 0OP or VAR) or else EXT for two-byte opcodes (where the
first byte is (decimal) 190).  The decimal number is the lowest possible
decimal opcode value (by convention, 256 is added for extended opcodes). 
The hex number is the opcode number within each |TYPE|.

The ``V" column gives the Version information.  If nothing is specified, the
opcode is as stated from Version 1 onwards.  Otherwise, it exists only from
the version quoted onwards.  Before this time, its use is illegal.  Some
opcodes change their meanings as the Version increases, and these have more
than one line of specification.  Others become illegal again, and these are
marked |[illegal]|.

In a few cases, the Version is given as ``3/4" or some such.  The first
number is the Version number whose specification the opcode belongs to, and
the second is the earliest Version in which the opcode is known actually to
be used in an Infocom-produced story file.  A dash means that it is seems
never to have been used (in any Version).

The table explicitly marks opcodes which do not exist in any version of the
Z-machine as |------|: in addition, none of the extended set of codes from
|$1d| to |$ff| were ever used.

\subtitle{Inform assembly language}

An Inform line beginning with an |@| is sent directly to the assembler. In
the syntax below, |<variable>| and |<result>| must be variables (or |sp|,
the stack pointer); |<label>| a label (not a routine name). 
|<literal-string>| must be literal text in quotation marks ``thus". 
|routine| should be the name of a routine (this assembles to its packed
address).  Otherwise any Inform constant term (such as |'/'| or |'beetle'|)
can be given as an operand.

In a branch instruction, the logical effect can be negated using a tilde
|~| before the label name, so for instance
\beginstt
    @je a b ~Different;  ! Jump to Different if a not equal to b
\endtt
The programmer must specify whether a branch is in the ``near" or ``far"
form, the default being ``near".  A question mark |?| before the label (and
tilde, if present) forces it to be ``far''.

Note that the operands marked as |<variable>| are assembled with ``small
constant'' type, not ``variable'' type (see \S 4.2.3).  This affects the
opcodes
\beginstt
    inc,  dec,  inc_chk,  dec_chk,  store,  pull,  load.
\endtt
For example, Inform assembles |@inc score;| to something looking like
``increment 16'', because 16 is the variable number of |score|.
(Such behaviour can be seen, for instance, at |$5051| in Zork II,
48.840904.  Some Infocom games use ``indirect addressing'' by
|load [sp] sp| (load the value of the variable held on the stack,
and put it on the stack).  However, this syntax is not understood
by Inform.)

\vfill\eject
\hrule\smallskip
\centerline{\bf Two-operand (long) opcodes 2OP}\smallskip\hrule
\beginlines
|   St  Br  Opcode Hex  V  Inform name and syntax|
\endlines\smallskip\hrule\smallskip\beginlines
|           ------   0  ------|
|       *   2OP:1    1     je              a b <label>|
|       *   2OP:2    2     jl              a b <label>|
|       *   2OP:3    3     jg              a b <label>|
|       *   2OP:4    4     dec_chk         <variable> value <label>|
|       *   2OP:5    5     inc_chk         <variable> value <label>|
|       *   2OP:6    6     jin             obj1 obj2 <label>|
|       *   2OP:7    7     test            bitmap flags <label>|
|   *       2OP:8    8     or              a b <result>|
|   *       2OP:9    9     and             a b <result>|
|       *   2OP:10   A     test_attr       object attribute <label>|
|           2OP:11   B     set_attr        object attribute|
|           2OP:12   C     clear_attr      object attribute|
|           2OP:13   D     store           <variable> value|
|           2OP:14   E     insert_obj      object destination|
|   *       2OP:15   F     loadw           array word-index <result>|
|   *       2OP:16  10     loadb           array byte-index <result>|
|   *       2OP:17  11     get_prop        object property <result>|
|   *       2OP:18  12     get_prop_addr   object property <result>|
|   *       2OP:19  13     get_next_prop   object property <result>|
|   *       2OP:20  14     add             a b <result>|
|   *       2OP:21  15     sub             a b <result>|
|   *       2OP:22  16     mul             a b <result>|
|   *       2OP:23  17     div             a b <result>|
|   *       2OP:24  18     mod             a b <result>|
|   *       2OP:25  19  4  call_2s         routine arg1 <result>|
|           2OP:26  1A  5  call_2n         routine arg1|
|           2OP:27  1B  5  set_colour      foreground background|
|           2OP:28  1C 5/- throw           value stack-frame|
|           ------  1D  ------|
|           ------  1E  ------|
|           ------  1F  ------|
\endlines\smallskip\hrule\smallskip
\centerline{32 to 127: other forms of 2OP with different types.}
\vfill\eject
\smallskip\hrule\smallskip
\centerline{\bf One-operand opcodes \rm 1OP}\smallskip\hrule
\beginlines
|   St  Br  Opcode Hex  V  Inform name and syntax|
\endlines\smallskip\hrule\smallskip\beginlines
|       *   1OP:128  0     jz              a <label>|
|   *   *   1OP:129  1     get_sibling     object <result> <label>|
|   *   *   1OP:130  2     get_child       object <result> <label>|
|   *       1OP:131  3     get_parent      object <result>|
|   *       1OP:132  4     get_prop_len    property-address <result>|
|           1OP:133  5     inc             <variable>|
|           1OP:134  6     dec             <variable>|
|           1OP:135  7     print_addr      byte-address-of-string|
|   *       1OP:136  8  4  call_1s         routine <result>|
|           1OP:137  9     remove_obj      object|
|           1OP:138  A     print_obj       object|
|           1OP:139  B     ret             value|
|           1OP:140  C     jump            <label>|
|           1OP:141  D     print_paddr     packed-address-of-string|
|   *       1OP:142  E     load            <variable> <result>|
|   *       1OP:143  F 1/4 not             value <result>|
|                       5  call_1n         routine|
\endlines\smallskip\hrule\smallskip
\centerline{144 to 175: other forms of 1OP with different types.}
\medskip\hrule\smallskip
\centerline{\bf Zero-operand opcodes \rm 0OP}\smallskip\hrule
\beginlines
|   St  Br  Opcode Hex  V  Inform name and syntax|
\endlines\smallskip\hrule\smallskip\beginlines
|           0OP:176  0     rtrue|
|           0OP:177  1     rfalse|
|           0OP:178  2     print           <literal-string>|
|           0OP:179  3     print_ret       <literal-string>|
|           0OP:180  4 1/- nop|
|       *   0OP:181  5  1  save            <label>|
|                       5  [illegal]|
|       *   0OP:182  6  1  restore         <label>|
|                       5  [illegal]|
|           0OP:183  7     restart|
|           0OP:184  8     ret_popped|
|           0OP:185  9  1  pop|
|   *                  5/- catch           <result>|
|           0OP:186  A     quit|
|           0OP:187  B     new_line|
|           0OP:188  C  3  show_status|
|                       4  [illegal]|
|       *   0OP:189  D  3  verify          <label>|
|           0OP:190  E  5  [first byte of extended opcode]|
|       *   0OP:191  F 5/- piracy          <label>|
\endlines\smallskip\hrule\smallskip
\centerline{192 to 223: VAR forms of 2OP:0 to 2OP:31.}
\vfill\eject
\smallskip\hrule\smallskip
\centerline{\bf Variable-operand opcodes \rm VAR}\smallskip\hrule
\beginlines
|   St  Br  Opcode Hex  V  Inform name and syntax|
\endlines\smallskip\hrule\smallskip\beginlines
|   *       VAR:224  0  1  call            routine ...up to 3 args... <result>|
|                          icall           packed-address-of-routine <result>|
|                       4  call_vs         routine ...up to 3 args... <result>|
|           VAR:225  1     storew          array word-index value|
|           VAR:226  2     storeb          array byte-index value|
|           VAR:227  3     put_prop        object property value|
|           VAR:228  4  1  sread           text parse|
|                       4  sread           text parse time routine|
|   *                   5  aread           text parse time routine <result>|
|           VAR:229  5     print_char      output-character-code|
|           VAR:230  6     print_num       value|
|   *       VAR:231  7     random          range <result>|
|           VAR:232  8     push            value|
|           VAR:233  9  1  pull            <variable>|
|   *                  6/- pull            stack <result>|
|           VAR:234  A  3  split_window    lines|
|           VAR:235  B  3  set_window      window|
|   *       VAR:236  C  4  call_vs2        routine ...up to 7 args... <result>|
|           VAR:237  D  4  erase_window    window|
|           VAR:238  E 4/- erase_line      value|
|                       6  erase_line      pixels|
|           VAR:239  F  4  set_cursor      line column|
|                       6  set_cursor      line column window|
|           VAR:240 10 4/- get_cursor      table|
|           VAR:241 11  4  set_text_style  style|
|           VAR:242 12  4  buffer_mode     flag|
|           VAR:243 13  3  output_stream   number|
|                       5  output_stream   number table|
|                       6  output_stream   number table width|
|           VAR:244 14  3  input_stream    number|
|           VAR:245 15 5/3 sound_effect    number effect volume routine|
|   *       VAR:246 16  4  read_char       1 time routine <result>|
|   *    *  VAR:247 17  4  scan_table      x table len|
|   *       VAR:248 18 5/- not             value <result>|
|           VAR:249 19  5  call_vn         routine ...up to 3 args...|
|           VAR:250 1A  5  call_vn2        routine ...up to 7 args...|
|           VAR:251 1B  5  tokenise        text parse dictionary flag|
|           VAR:252 1C  5  encode_text     ascii-text length from coded-text|
|           VAR:253 1D  5  copy_table      first second size|
|           VAR:254 1E  5  print_table     ascii-text width height skip|
|        *  VAR:255 1F  5  check_arg_count argument-number|
\endlines\smallskip\hrule\smallskip
\vfill\eject
\smallskip\hrule\smallskip
\centerline{\bf Extended opcodes \rm EXT}\smallskip\hrule
\beginlines
|   St  Br  Opcode Hex  V  Inform name and syntax|
\endlines\smallskip\hrule\smallskip\beginlines
|   *       EXT:256  0  5  save            table bytes name <result>|
|   *       EXT:257  1  5  restore         table bytes name <result>|
|   *       EXT:258  2  5  log_shift       number places <result>|
|   *       EXT:259  3 5/- art_shift       number places <result>|
|   *       EXT:260  4  5  set_font        font window <result>|
|           EXT:261  5  6  draw_picture    picture-number y x|
|        *  EXT:262  6  6  picture_data    picture-number table <label>|
|           EXT:263  7  6  erase_picture   picture-number y x|
|           EXT:264  8  6  set_margins     left right window|
|   *       EXT:265  9  5  save_undo       <result>|
|   *       EXT:266  A  5  restore_undo    <result>|
|           -------  B  ------|
|           -------  C  ------|
|           -------  D  ------|
|           -------  E  ------|
|           -------  F  ------|
|           EXT:272 10  6  move_window     window y x|
|           EXT:273 11  6  window_size     window y x|
|           EXT:274 12  6  window_style    window flags operation|
|   *       EXT:275 13  6  get_wind_prop   window property-number <result>|
|           EXT:276 14  6  scroll_window   window pixels|
|           EXT:277 15  6  pop_stack       items stack|
|           EXT:278 16  6  read_mouse      table|
|           EXT:279 17  6  mouse_window    window|
|        *  EXT:280 18  6  push_stack      value stack <label>|
|           EXT:281 19  6  put_wind_prop   window property-number value|
|           EXT:282 1A  6  print_form      formatted-table|
|        *  EXT:283 1B  6  make_menu       number table <label>|
|           EXT:284 1C  6  picture_table   table|
\endlines\smallskip\hrule\bigskip

\nsp{2} Formally, it is illegal for a game to contain an opcode
not specified for its version.  An interpreter should normally halt with
a suitable message.

\sp{2.1} However, extended opcodes in the range EXT:285 to EXT:511
should be simply ignored (perhaps with a warning message somewhere
off-screen).

\sp{2.2} EXT:285 to EXT:383 are reserved for future common extensions of
the Z-machine.

\sp{2.3} Game-writers who wish to create their own ``new'' opcodes, for one
specific game only, are asked to use opcode numbers in the range EXT:384 to
EXT:511.  It is easy to modify Inform to name and assemble such opcodes. 
(Of course the game will then have to be circulated with a suitably modified
interpreter to run it.)

\sp{2.4} Interpreter-writers should make this easy by providing a
routine which is called if EXT:384 to EXT:511 are found, so that
the minimum possible modification to the interpreter is needed.

\remarks
The opcodes 5, 6, 7, 8 in the extended set were very likely in Infocom's
own V5 specification (now lost): they seem to have been partially implemented
in existing Infocom interpreters, but do not occur in any existing V5
story file.  They are here left unspecified.

The notation ``5/3" for |sound_effect| is because this plainly
version-5 feature was used also in one solitary Version-3 game,
`The Lurking Horror' (the sound version of which was the last V3 release,
in September 1987).

The 2OP opcode 0 was possibly intended for setting break-points
in debugging.  It was not |nop|.  (The Infix debugger uses the actual
|nop| instruction as a break-point instead.)

|read_mouse| and |make_menu| are believed to have been used only in
`Journey' (based on a check of 11 V6 story files).  |picture_table| is
used once by `Shogun' and several times by `Zork Zero'.


\specs{15}{Dictionary of opcodes}

\quote
       The highest ideal of a translation... is achieved when the
       reader flings it impatiently into the fire, and begins
       patiently to learn the language for himself.
\quoteby{Philip Vellacott}

\sp{1} The dictionary below is alphabetical and includes entries on every
opcode listed in the table above, as well as brief notes on some Inform
internal synonyms which might otherwise be confused with opcodes.

\nsp{2} The Z-machine has the same concept of ``table'' (as an internal
data structure) as Inform.  Specifically, a table is an array of words
(in dynamic or static memory) of which the initial entry is the number
of subsequent words in the table.  For example, a table with three
entries occupies 8 bytes, arranged as the words 3, $x$, $y$, $z$.

\nsp{3} In all cases below where one operand is supposed to be an object
number, the behaviour is undefined if it isn't a legal object number
(and this includes 0).  Ideally an interpreter should halt with a suitable
error message.  This is especially true of |print_obj| (which is not
required to run very quickly, so that an interpreter can safely ``waste''
time checking this common error condition).  Similar remarks apply to
attribute numbers exceeding 32 or 48; and to window numbers, window
attribute numbers and window property numbers in Version 6.
\bigskip
\stepin=75pt
\ninepoint
\def\de{\medskip\noindent}

\block{add}|2OP:20  14     add             a b <result>|
    \continue
    Signed 16-bit addition.

\block{and}|2OP:9    9     and             a b <result>|
    \continue
    Bitwise AND.

\block{"aparse"}Obsolete name for |tokenise|.

\block{aread}This is the Inform name for the keyboard-reading opcode
    under Version 5 and later.  (Inform calls the same opcode |sread|
    under Versions 3 and 4.)  See |read| for the specification.

\block{art\_shift}|EXT:259  3 5/- art_shift       number places <result>|
    \continue
    Does an arithmetic shift of |number| by the given number
    of places, shifting left (i.e. increasing) if places is positive, right
    if negative.  In a right shift, the sign bit is preserved as well as
    being shifted on down.  (The alternative behaviour is |log_shift|.)

\block{"beep"}Inform currently uses this name for |sound_effect| in Versions
    before 5 (since public interpreters provide only minimal facilities),
    but the name is being withdrawn.  See |sound_effect|.

\block{buffer\_mode}|VAR:242 12  4  buffer_mode     flag|
    \continue
    If set to 1, text output on the lower window in stream 1
    is buffered up so that it can be word-wrapped properly.  If set to 0, it
    isn't.

\block{call}|VAR:224  0  1  call            routine ...up to 3 args... <result>|
    \continue
    The only call instruction in Version 3, Inform reads this as
    |call_vs| in higher versions: it calls the routine with 0, 1, 2 or 3
    arguments as supplied and stores the resulting return value.  (When the
    address 0 is called as a routine, nothing happens and the return value
    is false.)

\block{call\_1n}|1OP:143  F  5  call_1n         routine|
    \continue
    Executes |routine()| and throws away result.

\block{call\_1s}|1OP:136  8  4  call_1s         routine <result>|
    \continue
    Stores |routine()|.

\block{call\_2n}|2OP:26  1A  5  call_2n         routine arg1|
    \continue
    Executes |routine(arg1)| and throws away result.

\block{call\_2s}|2OP:25  19  4  call_2s         routine arg1 <result>|
    \continue
    Stores |routine(arg1)|.

\block{call\_vn}|VAR:249 19  5  call_vn         routine ...up to 3 args...|
    \continue
    Like |call|, but throws away result.

\block{call\_vs}|VAR:224  0  4  call_vs         routine ...up to 3 args... <result>|
    \continue
    See |call|.

\block{call\_vn2}|VAR:250 1A  5  call_vn2        routine ...up to 7 args...|
    \continue
    Call with a variable number (from 0 to 7) of arguments, then
    throw away the result.  This (and |call_vs2|) uniquely have an extra byte
    of opcode types to specify the types of arguments 4 to 7.  Note that it is
    legal to use these opcodes with fewer than 4 arguments (in which case the
    second byte of type information will just be |$ff|).

\block{call\_vs2}|VAR:236  C  4  call_vs2        routine ...up to 7 args... <result>|
    \continue
    See |call_vn2|.

\block{catch}|0OP:185  9  5  catch           <result>|
    \continue
    Opposite to |throw| (and occupying the same opcode that |pop|
    used in Versions 3 and 4).  |catch| returns the current ``stack frame''.

\block{check\_arg\_count}|VAR:255 1F  5  check_arg_count argument-number|
    \continue
    Branches if the given argument-number (counting
    from 1) has been provided by the routine call to the current routine.
    (This allows routines in Versions 5 and later to distinguish between
    the calls |routine(1)| and |routine(1,0)|, which would otherwise be
    impossible to tell apart.)

\block{"check\_no\_args"}Obsolete name for |check_arg_count|.

\block{clear\_attr}|2OP:12   C     clear_attr      object attribute|
    \continue
    Make |object| not have the attribute numbered |attribute|.

\block{"clear\_flag"}A name once used for one of the not-really-present
    extended Version 5 opcodes (now removed from the specification).

\block{"colour"}Obsolete name for |set_colour|.

\block{"compare\_pobj"}Obsolete name for |jin|.

\block{copy\_table}|VAR:253 1D  5  copy_table      first second size|
    \continue
    Copies |size| bytes from the |first| table to
    the |second|.  If |second| table is 0, then it zeroes the bytes in
    |first|.
    \continue
    If |size| is positive, copying takes place backwards:
    \continue |copy_table $1000 $1001 20|
    \continue
    pushes the first 20 bytes forward by one.  However, if the |size| is
    negative then copying is forwards.  Thus the same operation with |size|
    -20 would result in the byte at |$1000| being copied into the 20
    following bytes.

\block{dec}|1OP:134  6     dec             <variable>|
    \continue
    Decrement variable by 1.  This is signed, so $0$ decrements to $-1$.

\block{dec\_chk}|2OP:4    4     dec_chk         <variable> value <label>|
    \continue
    Decrement variable, and branch if it is now less than the given value.

\block{div}|2OP:23  17     div             a b <result>|
    \continue
    Unsigned 16-bit division.  Division by zero
    should halt the interpreter with a suitable error message.

\block{draw\_picture}|EXT:261  5  6  draw_picture    picture-number y x|
    \continue
    Displays the picture with the given number.  $(y,x)$
    coordinates (of the top left of the picture) are optional: if they are
    zero or not supplied, then the picture appears in the current window at
    the current cursor position.  It is illegal to call this with an invalid
    picture number.

\block{encode\_text}|VAR:252 1C  5  encode_text     ascii-text length from coded-text|
    \continue
    Translates an ASCII word to Z-encoded text format
    (stored at |coded-text|), as if it were an entry in the dictionary.
    The text begins at |from| in the |ascii-text| buffer and is |length|
    characters long.  (Some interpreters ignore this and keep translating
    until they hit a 0 character anyway, or have already filled up the 6-byte
    Z-encoded string.)

\block{"encrypt"}Obsolete name for |encode_text|.

\block{erase\_line}|VAR:238  E 4/- erase_line      value|
    \continue
    Before Version 6: erase from the current cursor position
    to the end of the its line in the current window.  Version 6: if the value
    is 1, do just that: if not, erase the given number of pixels minus one
    across from the cursor (clipped to stay inside the right margin).  The
    cursor does not move.

\block{erase\_picture}|EXT:263  7  6  erase_picture   picture-number y x|
    \continue
    Like |draw_picture|, but paints the appropriate region
    to the background colour for the given window.  It is illegal to call this
    with an invalid picture number.

\block{erase\_window}|VAR:237  D  4  erase_window    window|
    \continue
    Erases window with given number (to background colour);
    or if -1 it unsplits the screen and clears the lot (see \S 8); or if
    -2 it clears the screen without unsplitting it.  In cases -1 and -2, the
    cursor moves back to top left.

\block{"extended"}This byte (decimal 190) is not an instruction, but
    indicates that the opcode is ``extended": the next byte contains the
    number in the extended set.

\block{get\_next\_prop}|2OP:19  13     get_next_prop   object property <result>|
    \continue
    Gives the number of the next property provided by the
    quoted object.  This may be zero, indicating the end of the property list;
    if called with zero, it gives the first property number present.  It is
    illegal to try to find the next property of a property which does not
    exist, and an interpreter should halt with an error message (if it can
    efficiently check this condition).

\block{get\_prop}|2OP:17  11     get_prop        object property <result>|
    \continue
    Read property from object (resulting in the default value
    if it had no such declared property).  If the property has length 1, the
    value is only that byte.  Otherwise, the first two bytes of the property
    are taken as a word value.  (It is legal to apply |get_prop| to an array
    property, i.e. a property of length greater than 2, but |ITF| behaves
    strangely in this case.)

\block{get\_prop\_addr}|2OP:18  12     get_prop_addr   object property <result>|
    \continue
    Get the byte address (in dynamic memory) of the
    property data for the given object's property.  This must return 0 if
    the object hasn't got the property.

\block{get\_prop\_len}|1OP:132  4     get_prop_len    property-address <result>|
    \continue
    Get length of property data (in bytes) for the given
    object's property.  It is illegal to try to find the property length
    of a property which does not exist for the given object, and an
    interpreter should halt with an error message (if it can efficiently
    check this condition).

\block{get\_child}|1OP:130  2     get_child       object <result> <label>|
    \continue
    Get first object contained in given object, branching if
    this exists, i.e. is not |nothing| (i.e., is not 0).

\block{get\_cursor}|VAR:240 10 4/- get_cursor      table|
    \continue
    Puts the current cursor row into the first word of the
    given table, and the current cursor column into the second word.

\block{get\_parent}|1OP:131  3     get_parent      object <result>|
    \continue
    Get parent object (note that this has no ``branch if
    exists" clause).

\block{get\_sibling}|1OP:129  1     get_sibling     object <result> <label>|
    \continue
    Get next object in tree, branching if this exists, i.e.
    is not 0.

\block{get\_wind\_prop}|EXT:275 13  6  get_wind_prop   window property-number <result>|
    \continue
    Reads the given property of the given window (see
    \S 8).

\block{"icall"}This is an Inform internal name for ``call to a routine whose
    address is supplied, not its name", used in the implementation of the
    Inform |indirect| function.

\block{inc}|1OP:133  5     inc             <variable>|
    \continue
    Increment variable by 1.  (This is signed, so $-1$ increments
    to 0.)

\block{inc\_chk}|2OP:5    5     inc_chk         <variable> value <label>|
    \continue
    Increment variable, and branch if now greater than value.

\block{input\_stream}|VAR:244 14  3  input_stream    number|
    \continue
    Selects the current input stream.

\block{insert\_obj}|2OP:14   E     insert_obj      object destination|
    \continue
    Moves object $O$ to become the first child of the
    destination object $D$.  (Thus, after the operation the |child| of $D$
    is $O$, and the |sibling| of $O$ is whatever was previously the |child|
    of $D$.)  All children of $O$ move with it.  (Initially $O$ can be at
    any point in the object tree; it may legally have |parent| zero.)

\block{je}|2OP:1    1     je              a b <label>|
    \continue
    Jump if |a| is equal to any of the subsequent operands.  (Thus
    |@je a| never jumps and |@je a b| jumps if |a = b|.)

\block{jg}|2OP:3    3     jg              a b <label>|
    \continue
    Jump if |a > b| (using a signed 16-bit comparison).

\block{"jge"}An old, confusing name for |jg|, long since withdrawn.

\block{jin}|2OP:6    6     jin             obj1 obj2 <label>|
    \continue
    Jump if object |a| is a direct child of |b|, i.e., if
    |parent| of |a| is |b|.

\block{jl}|2OP:2    2     jl              a b <label>|
    \continue
    Jump if |a < b| (using a signed 16-bit comparison).

\block{"jle"}An old, confusing name for |jl|, long since withdrawn.

\block{jump}|1OP:140  C     jump            <label>|
    \continue
    Jump (unconditionally) to the given label.  (This is not a
    branch instruction and the operand is a 2-byte signed offset to apply
    to the program counter.)  It is legal for this to jump into a different
    routine (which should not change the routine call state), although it
    is considered bad practice to do so and the |Txd| disassembler is
    confused by it.

\block{jz}|1OP:128  0     jz              a <label>|
    \continue
    Jump if |a = 0|.

\block{load}|1OP:142  E     load            <variable> <result>|
    \continue
    The value of the variable referred to by the operand
    is stored in the result.  (Inform doesn't use this; see the notes to
    \S 14.)

\block{loadb}|2OP:16  10     loadb           array byte-index <result>|
    \continue
    Stores |array->byte-index| (i.e., the byte at address
    |array+byte-index|, which must lie in static or dynamic memory).

\block{loadw}|2OP:15   F     loadw           array word-index <result>|
    \continue
    Stores |array-->word-index| (i.e., the word at address
    |array+2*word-index|, which must lie in static or dynamic memory).

\block{log\_shift}|EXT:258  2  5  log_shift       number places <result>|
    \continue
    Does a logical shift of |number| by the given number of
    |places|, shifting left (i.e. increasing) if |places| is positive, right
    if |negative|.  In a right shift, the sign is zeroed instead of being
    shifted on.  (See also |art_shift|.)

\block{"lstore"}An internal Inform name for ``the long form of |store|''.

\block{make\_menu}|EXT:283 1B  6  make_menu       number table <label>|
    \continue
    Controls menus with numbers greater than 2 (i.e., it
    doesn't control the three system menus).  If the table supplied is 0,
    the menu is removed.  Otherwise it is a table of tables.  Each table is
    an ASCII string: the first item being a menu name, subsequent ones the
    entries.

\block{mod}|2OP:24  18     mod             a b <result>|
    \continue
    Remainder after unsigned 16-bit division.  Division by zero
    should halt the interpreter with a suitable error message.

\block{mouse\_window}|EXT:279 17  6  mouse_window    window|
    \continue
    Constrain the mouse arrow to sit inside the given window.
    By default it sits in window 1.  Setting to -1 takes all restriction away.
    (The mouse clicks are not reported if the arrow is outside the window
    and interpreters are presumably supposed to hold the arrow there by
    hardware means if possible.)

\block{move\_window}|EXT:272 10  6  move_window     window y x|
    \continue
    Moves the given window to pixels $(y,x)$: $(1,1)$ being
    the top left.  Nothing actually happens (since windows are entirely
    notional transparencies): but any future plotting happens in the new place.

\block{mul}|2OP:22  16     mul             a b <result>|
    \continue
    Signed 16-bit multiplication.

\block{new\_line}|0OP:187  B     new_line|
    \continue
    Print carriage return.

\block{nop}|0OP:180  4 1/- nop|
    \continue
    Probably the official ``no operation" instruction, which,
    appropriately, was never operated (in any of the Infocom datafiles).
    It is conceivably useful for self-modifying code, and this is
    conceivably possible in the Z-machine: so the author would like to
    specify it as |nop|.

\block{not}|1OP:143  F 1/4 not             value <result>|
    \continue
    Bitwise NOT (i.e., all 16 bits reversed).  Note: in Versions
    3 and 4 this is a 1OP instruction (as expected) but in later Versions
    it was moved into the extended set to make room for |call_1n|.
    (The Inform assembler knows which opcode number to assemble to.)

\block{or}|2OP:8    8     or              a b <result>|
    \continue
    Bitwise OR.

\block{output\_stream}%
|VAR:243 13  3  output_stream   number|
    \continue
    |            5  output_stream   number table|
    \continue
    |            6  output_stream   number table width|
    \continue
    If |stream| is 0, nothing happens.  If it is
    positive, then that stream is selected; if negative, deselected.
    (Recall that several different streams can be selected at once.)
    \continue
    When stream 3 is selected, a |table| must be given into which text
    can be printed.  The first word always holds the number of characters
    printed, the actual text being stored at bytes |table+2| onward.
    It is not the interpreter's responsibility to worry about the length
    of this table being overrun.
    \continue
    In Version 6, a |width| field may optionally be given: if this is
    non-zero, text will then be justified as if it were in the window with
    that number (if width is positive) or a box -|width| pixels wide (if
    negative).  Then the table will contain not ordinary text but formatted
    text: see |print_form|.

\block{picture\_data}|EXT:262  6  6  picture_data    picture-number table <label>|
    \continue
    Asks the interpreter for data on the picture with
    the given number.  If the picture number is valid, a branch occurs and
    information is written to the table: the height in the first word,
    the width in the second, in pixels.
    \continue
    Otherwise, if the picture number is zero, the interpreter writes the
    highest legal picture number into the first word of the table.
    \continue
    Otherwise, nothing happens.

\block{picture\_table}|EXT:284 1C  6  picture_table   table|
    \continue
    (Warning: this is only a conjecture.)  Given
    a table of picture numbers, load in these pictures from disc into a cache
    for convenient rapid plotting later.  (For instance, the peggleboard
    sprites in `Zork Zero'.)

\block{piracy}|0OP:191  F 5/- piracy          <label>|
    \continue
    Branches if the game disc is believed to be genuine by the
    interpreter (which is assumed to have some arcane way of finding out).
    Interpreters are asked to be gullible and to unconditionally branch.

\block{pop}|0OP:185  9  1  pop|
    \continue
    Throws away the top item on the stack.  (This was useful to
    lose unwanted routine call results in early Versions.)

\block{pop\_stack}|EXT:277 15  6  pop_stack       items stack|
    \continue
    The given number of items are thrown away from the top
    of a stack: by default the system stack, otherwise the one given as a
    second operand.

\block{print}|0OP:178  2     print           <literal-string>|
    \continue
    Print the quoted (literal) Z-encoded string.

\block{print\_addr}|1OP:135  7     print_addr      byte-address-of-string|
    \continue
    Print (Z-encoded) string at given byte address,
    in dynamic or static memory.

\block{print\_char}|VAR:229  5     print_char      output-character-code|
    \continue
    Print `ASCII' character.  The operand is interpreted
    as an extended `ASCII' code, as specified in \S 3.  The operand
    may not legally be (negative or) larger than 1023.

\block{print\_form}|EXT:282 1A  6  print_form      formatted-table|
    \continue
    Prints a formatted table of the kind written to
    output stream 3 when formatting is on.  This is an elaborated version
    of |print_table| to cope with
    fonts, pixels and other impedimenta.  It is a sequence of lines,
    terminated with a zero word.  Each line is a word containing the number
    of characters, followed by that many bytes which hold the characters
    concerned.

\block{print\_num}|VAR:230  6     print_num       value|
    \continue
    Print (signed) number in decimal.

\block{print\_obj}|1OP:138  A     print_obj       object|
    \continue
    Print short name of object (the Z-encoded string in the
    object header, not a property).  If the object number is invalid, the
    interpreter should halt with a suitable error message.

\block{print\_paddr}|1OP:141  D     print_paddr     packed-address-of-string|
    \continue
    Print the (Z-encoded) string at the given packed
    address in high memory.

\block{print\_ret}|0OP:179  3     print_ret       <literal-string>|
    \continue
    Print the quoted (literal) Z-encoded string, then print
    a new-line and then return true (i.e., 1).

\block{print\_table}|VAR:254 1E  5  print_table     ascii-text width height skip|
    \continue
    Print a rectangle of text on screen spreading right and
    down from the current cursor position, of given |width| and |height|, from
    the table of ASCII text given.  (Height is optional and defaults to 1.)
    If a |skip| value is given, then that many characters of text are skipped
    over in between each line and the next.  (So one could make this display,
    for instance, a 2 by 3 window onto a giant 40 by 40 character graphics
    map.)
    \continue
    Some Infocom-written interpreters stop printing if a zero byte is found
    in the text: this is not understood.  Future games should not include
    a zero byte in a table to be printed.


\block{pull}|VAR:233  9  1  pull            <variable>|
    \continue
    |           6/- pull            stack <result>|
    \continue
    Pulls value off a stack.  (If the stack underflows, the
    interpreter should halt with a suitable error message.)  In Version 6,
    the stack in question may be specified as a user one: otherwise it
    is the game stack.

\block{push}|VAR:232  8     push            value|
    \continue
    Pushes value onto the game stack.

\block{push\_stack}|EXT:280 18  6  push_stack      value stack <label>|
    \continue
    Pushes the value onto the specified user stack, and
    branching if this was successful.  If the stack overflows, nothing
    happens (this is not an error condition).

\block{put\_prop}|VAR:227  3     put_prop        object property value|
    \continue
    Writes the given value to the given property of the
    given object.  If the property does not exist for that object, the
    interpreter should halt with a suitable error message.  If the
    property length is 1, then the interpreter should store only the
    least significant byte of the value.  (For instance, storing $-1$
    into a 1-byte property results in the property value 255.)
    Otherwise the value is stored in the first word of the property data.

\block{put\_wind\_prop}|EXT:281 19  6  put_wind_prop   window property-number value|
    \continue
    Writes a window property (see |get_wind_prop|).
    This should only be used when there is no direct command (such as
    |move_window|) to use instead, as some such operations may have
    side-effects.

\block{quit}|0OP:186  A     quit|
    \continue
    Exit the game immediately.  (Any ``Are you sure?" question
    must be asked by the game, not the interpreter.)  It is not legal to
    return from the main routine (that is, from where execution first
    begins) and this must be used instead.

\block{random}|VAR:231  7     random          range <result>|
    \continue
    If |range| is positive, returns a uniformly random number
    between 1 and |range|.  If |range| is negative, the random number generator
    is seeded to that value and the return value is 0.  Most interpreters
    consider giving 0 as |range| illegal (because they attempt a division
    with remainder by the |range|), but correct behaviour is to reseed the
    generator in as random a way as the interpreter can (e.g. by using the
    time in milliseconds).
    \continue
    (Some version 3 games, such as `Enchanter' release 29, had a debugging
    verb |#random| such that typing, say, |#random 14| caused a call of
    |random| with -14.)

\block{read}|VAR:228  4  1  sread           text parse|
    \continue
    |            4  sread           text parse time routine|
    \continue
    |            5  aread           text parse time routine <result>|
    \continue
    (Note that Inform internally names the |read| opcode as |aread|
    in Versions 5 and later and |sread| in Versions 3 and 4.)
    \continue
    This opcode reads a whole command from the keyboard (no prompt is
    automatically displayed).  It is legal for this to be called with the
    cursor at any position on any window.
    \continue
    In Versions 1 to 3, the status line is automatically redisplayed first.
    \continue
    A sequence of characters is read in from the current input stream until
    a carriage return (or, in Versions 5 and later, any terminating character)
    is found.
    \continue
    In Versions 1 to 4, byte 0 of the |text-buffer| should initially contain
    the maximum number of letters which can be typed, minus 1 (the interpreter
    should not accept more than this).  The text typed is reduced to lower case
    (so that it can tidily be printed back by the program if need be)
    and stored in bytes 1 onward, with a zero terminator (but without any other
    terminator, such as a carriage return code).  (This means that
    if byte 0 contains $n$ then the buffer must contain $n+1$ bytes, which
    makes it a |string| array of length $n$ in Inform terminology.)
    \continue
    In Versions 5 and later, byte 0 of the |text-buffer| should initially contain
    the maximum number of letters which can be typed (the interpreter should
    not accept more than this).  The interpreter stores the number of characters
    actually typed in byte 1 (not counting the terminating character), and the
    characters themselves in bytes 2 onward (not storing the terminating
    character).  (Some interpreters wrongly add a zero byte after the text anyway,
    so it is wise for the buffer to contain at least $n+3$ bytes.)  Moreover,
    if byte 1 contains a positive value at the start of the
    input, then |read| assumes that number of characters are left over from an
    interrupted previous input, and writes the new characters after those
    already there.  (This is used by `Beyond Zork' to handle function key
    presses during input.)
    \continue
    In Version 4 and later, if the operands |time| and |routine| are
    supplied (and non-zero) then the routine call |routine()| is
    made every |time/10| seconds during the keyboard-reading process.  If
    this routine returns true, all input is erased (to zero) and the
    reading process is terminated at once.  (The terminating character code
    is 0.)  The |routine| is permitted to print to the screen even if it
    returns false to signal ``carry on'': the interpreter should notice and
    redraw the input line so far, before input continues.
    \continue
    (Note that |Zip| contains a bug causing |routine| to be called
    with |time| as an argument, owing to a misunderstanding arising from a
    usage in `Border Zone': and calls it every |time| seconds, not every
    |time/10| seconds.  These two bugs cancel each other out so that
    `BZ' does in fact run (roughly) correctly.  However, Infocom's own
    interpreters run the infamous `Freefall' much faster than modern ones.)
    \continue
    Next, lexical analysis is performed on the text (except that in Versions 5
    and later, if |parse-buffer| is zero then this is omitted).  Initially,
    byte 0 of the |parse-buffer| should hold the maximum number of textual
    words which can be parsed.  (If this is $n$, the buffer must be at least
    $2+4*n$ bytes long to hold the results of the analysis.)
    \continue
    The interpreter divides the text into words and looks them up in the
    dictionary, as described in \S 13.  The number of words is written in
    byte 1 and one 4-byte block is
    written for each word, from byte 2 onwards (except that it should stop
    before going beyond the maximum number of words specified).  Each block
    consists of the byte address
    of the word in the dictionary, if it is in the dictionary, or 0 if it isn't;
    followed by a byte giving the number of letters in the word; and finally
    a byte giving the position in the |text-buffer| of the first letter of
    the word.
    \continue 
    In Version 5 and later, this is a store instruction: the return value
    is the terminating character (note that the user pressing his ``enter''
    key may cause either 10 or 13 to be returned; the author recommends
    that interpreters return 10).  A timed-out input returns 0.
    \continue
    (Versions 1 and 2 and early Version 3 games mistakenly write the parse buffer
    length 240 into byte 0 of the parse buffer: later games fix this bug and
    write 59, because $2+4\times 59 = 238$ so that 59 is the maximum number
    of textual words which can be parsed into a buffer of length 240 bytes.  The
    Inform library makes a similar mistake.  Neither mistake has very serious
    consequences.)
    \continue
    (Interpreters are asked to halt with a suitable error message if
    the text or parse buffers have length of less than 3 or 6 bytes,
    respectively: this sometimes occurs due to a previous array being
    overrun, causing bugs which are very difficult to find.)

\block{read\_char}|VAR:246 16  4  read_char       1 time routine <result>|
    \continue
    Reads a single character from input stream 0 (the
    keyboard).  The first operand must be 1 (presumably it was provided
    to support multiple input devices, but only the keyboard was ever
    used).  |time| and |routine| are optional (in Versions 4 and
    later only) and dealt with as in |read| above.

\block{read\_mouse}|EXT:278 16  6  read_mouse      table|
    \continue
    The four words in the |table| are written with the mouse
    y coordinate, x coordinate, button bits (low bits on the right of the
    mouse, rising as one looks left), and a menu word.  In the menu word,
    the upper byte is the menu number and the lower byte is the
    item number (from 0).

\block{remove\_obj}|1OP:137  9     remove_obj      object|
    \continue
    Detach the object from its parent, so that it no longer
    has any parent.  (Its children remain in its possession.)

\block{restart}|0OP:183  7  1  restart|
    \continue
    Restart the game.  (Any ``Are you sure?" question
    must be asked by the game, not the interpreter.)  The unique piece of
    information surviving from the previous state is the ``transcribing
    to printer'' bit (bit 0 of `Flags 2' in the header, at address |$10|),
    so that restarts are neatly printed in transcripts.
    (In particular, changing the program start address before a restart will
    not have the effect of restarting from this new address.)

\block{restore}|0OP:182  6  1  restore         <label>|
    \continue
    |EXT:257  1  5  restore         table bytes name <result>|
    \continue
    See |save|.  In Version 3, the branch is never actually made,
    since either the game has successfully picked up again from where it
    was saved, or it failed to load the save game file.
    \continue
    As with |restart|, the transcription bit survives.  The interpreter
    gives the game a way of knowing that a restore has just happened
    (see |save|).
    \continue
    From Version 5
    it can have optional parameters as |save| does, and returns the number
    of bytes loaded if so.  If the restore fails, 0 is returned, but once
    again this necessarily happens since otherwise control is already
    elsewhere.

\block{restore\_undo}|EXT:266  A  5  restore_undo    <result>|
    \continue
    Like |restore|, but restores the state saved to memory
    by |save_undo|.  (The optional parameters of |restore| may not be
    supplied.)  The behaviour of |restore_undo| is unspecified if no
    |save_undo| has previously occurred (and a game may not legally use it):
    an interpreter might simply ignore this.

\block{ret}|1OP:139  B     ret             value|
    \continue
    Returns from the current routine with the value given.

\block{ret\_popped}|0OP:184  8     ret_popped|
    \continue
    Pops top of stack and returns that.  (This is equivalent
    to |ret sp|, but is one byte cheaper.)

\block{"retsp"}Obsolete name for |ret_popped|.

\block{rfalse}|0OP:177  1     rfalse|
    \continue
    Return false (i.e., 0) from the current routine.

\block{rtrue}|0OP:176  0     rtrue|
    \continue
    Return true (i.e., 1) from the current routine.

\block{"same\_parent"}An obsolete (and misguided) Inform name for the
    opcode now called |jin|.

\block{save}|0OP:181  5  1  save            <label>|
    \continue
    On Versions 3 and 4, attempts to save the game (all questions
    about filenames are asked by interpreters) and branches if successful.
    From Version 5 it is a store rather than a branch instruction;
    the store value is 0 for failure, 1 for ``save succeeded" and 2 for
    ``the game is being restored and is resuming execution again from here,
    the point where it was saved".
    \continue
    The extension also has (optional) parameters, which save a region of
    the save area, whose address and length are in bytes, and provides a
    suggested filename: name is a pointer to an array of ASCII characters
    giving this name (as usual preceded by a byte giving the number of
    characters).  See \S 7.6.

\block{save\_undo}|EXT:265  9  5  save_undo       <result>|
    \continue
    Like |save|, except that the optional parameters may not
    be specified: it saves the game into a cache of memory held by the
    interpreter.  If the interpreter is unable to provide this feature, it
    must return -1: otherwise it returns the |save| return value.
    \continue
    (This call is typically needed once per turn, in order to implement
    ``UNDO", so it needs to be quick.)

\block{scan\_table}|VAR:247 17  4  scan_table      x table len|
    \continue
    Is |x| one of the words in |table|, which is |len| words
    long?  If so, return the address where it first occurs and branch.  If not,
    return 0 and don't.
    \continue
    The |form| is optional (and only used in Version 5?): bit 8 is set for
    words, clear for bytes: the rest contains the length of each field in
    the table.  (The first word or byte in each field being the one looked
    at.)  Thus |$82| is the default.

\block{"scanw"}Obsolete name for |scan_table|.

\block{scroll\_window}|EXT:276 14  6  scroll_window   window pixels|
    \continue
    Scrolls the given window by the given number of pixels
    (a negative value scrolls backwards, i.e., down) writing in blank
    (background colour) pixels in the new lines.  This can be done to any
    window and is not related to the ``scrolling" attribute of a window.

\block{set\_attr}|2OP:11   B     set_attr        object attribute|
    \continue
    Make |object| have the attribute numbered |attribute|.

\block{set\_colour}|2OP:27  1B  5  set_colour      foreground background|
    \continue
    If coloured text is available, set text to be
    foreground-against-background.
    \continue
    (One Version 5 game uses this: `Beyond Zork' (Paul David Doherty reports
    it as used ``76 times in 870915 and 870917, 58 times in 871221'') and from
    the structure of the table it clearly logically belongs in version 5.)

\block{set\_cursor}|VAR:239  F  4  set_cursor      line column|
    \continue
    |            6  set_cursor      line column window|
    \continue
    Move cursor in the current window to $(x,y)$ character
    position (relative to $(1,1)$ in the top left).  (In Version 6 the
    window is supplied and need not be the current one.)  Using this call may
    result in any buffered text being printed out first (if word-wrapping is
    going on, for instance).
    \continue
    In Version 6, |set_cursor -1| turns the cursor off, and either
    |set_cursor -2| or |set_cursor -2 0| turn it back on.  It is not known
    what, if anything, this second argument means: in all known cases it is 0.

\block{"set\_flag"}See |clear_flag|.

\block{set\_font}|EXT:260  4  5  set_font        font window <result>|
    \continue
    If the requested font is available, then it is chosen as
    the font for the given window, and the store value is the font ID of
    the previous font (which is always positive).  If the font is unavailable,
    nothing will happen and the store value is 0.

\block{set\_margins}|EXT:264  8  6  set_margins     left right window|
    \continue
    Sets the margin widths (in pixels) on the left and right
    for the given window (which are by default 0).

\block{set\_text\_style}|VAR:241 11  4  set_text_style  style|
    \continue
    Sets the text style to: Roman (if 0), Reverse
    Video (if 1), Bold (if 2), Italic (4), Fixed Pitch (8).  In some
    interpreters (though this is not required) a combination of styles is
    possible (such as reverse video and bold).  In these, changing to
    Roman should turn off all the other styles currently set.

\block{set\_window}|VAR:235  B  3  set_window      window|
    \continue
    Selects the given window for text output.

\block{"show\_score"}Obsolete name for |show_status|.

\block{show\_status}|0OP:188  C  3  show_status|
    \continue
    (In Version 3 only.)  Display and update the
    status line now (don't wait until the next keyboard input).  (In theory
    this opcode is illegal in later Versions but an interpreter should treat
    it as |nop|, because Version 5 Release 23 of `Wishbringer' contains
    this opcode by accident.)

\block{sound\_effect}|VAR:245 15 5/3 sound_effect    number effect volume routine|
    \continue
    (Inform also uses the name |beep| for this opcode,
    though this name is being withdrawn.)
    \continue
    The given effect happens to the given sound number.  The low byte of
    |volume| holds the volume level, the high byte the number of repeats.
    (The value 255 means ``loudest possible'' and ``forever'' respectively.)
    (In Version 3, repeats are unsupported and the high byte must be 0.)
    \continue
    The |effect| can be: 1 (prepare), 2 (start), 3 (stop), 4 (finish with).
    \continue
    In Versions 5 and later, the |routine| is called (with no parameters)
    after the sound has been finished (it has been playing in the background
    while the Z-machine has been working on other things).  (This is used by
    `Sherlock' to implement fading in and out, which explains why mysterious
    numbers like |$34FB| were previously thought to be to do with fading.)
    The routine is not called if the sound is stopped by another sound or by
    an effect 3 call.
    \continue
    See the remarks to \S 9 for which forms of this opcode were actually
    used by Infocom.
    \continue
    In theory, |@sound_effect;| (with no operands at all) is illegal.
    However interpreters are asked to beep (as if the operand were 1) if
    possible, and in any case not to halt.

\block{split\_window}|VAR:234  A  3  split_window    lines|
    \continue
    Splits the screen so that the upper window has the
    given number of lines: or, if this is zero, unsplits the screen again.
    In Version 6, this is supposed to roughly emulate the earlier Version
    behaviour (see \S 8).  (However, existing Version 6 games seem to use
    it just for bounding cursor movement.  `Journey' creates a status region
    which is the whole screen and then overlays it with two other windows.)

\block{sread}This is the Inform name for the keyboard-reading opcode
    under Versions 3 and 4.  (Inform calls the same opcode |aread| in later
    Versions.)  See |read| for the specification.

\block{store}|2OP:13   D     store           <variable> value|
    \continue
    Set the |variable| referenced by the operand to |value|.

\block{storeb}|VAR:226  2     storeb          array byte-index value|
    \continue
    |array->byte-index = value|, i.e. stores the given value
    in the byte at address |array+byte-index| (which must lie in dynamic
    memory).  (See |loadb|.)

\block{storew}|VAR:225  1     storew          array word-index value|
    \continue
    |array-->word-index = value|, i.e. stores the given value
    in the word at address |array+2*word-index| (which must lie in dynamic
    memory).  (See |loadw|.)

\block{sub}|2OP:21  15     sub             a b <result>|
    \continue
    Signed 16-bit subtraction.

\block{test}|2OP:7    7     test            bitmap flags <label>|
    \continue
    Jump if all of the flags in bitmap are set
    (i.e. if |bitmap & flags == flags|).

\block{"test\_array"}See |clear_flag|.  (|ITF| implements this as
    unconditionally false.)

\block{test\_attr}|2OP:10   A     test_attr       object attribute <label>|
    \continue
    Jump if |object| has |attribute|.

\block{throw}|2OP:28  1C 5/- throw           value stack-frame|
    \continue
    Opposite of |catch|: resets the routine call state to
    the state it had when the given stack frame value was `caught', and
    then returns.  In other words, it returns as if from the routine
    which executed the |catch| which found this stack frame value.

\block{tokenise}|VAR:251 1B  5  tokenise        text parse dictionary flag|
    \continue
    This performs lexical analysis (see |read| above).
    \continue
    If a non-zero |dictionary| is supplied, it is used (if not, the ordinary
    game dictionary is).  If the |flag| is set, unrecognised words are not
    written into the parse buffer and their slots are left unchanged: this
    is presumably so that if several |tokenise| instructions are performed
    in a row, each fills in more slots without wiping those
    filled by the others.
    \continue
    Parsing a user dictionary is slightly different.  A user dictionary
    should look just like the main one but need not be alphabetically sorted.
    If the number of entries is given as $-n$, then the interpreter reads
    this as ``$n$ entries unsorted".  This is very convenient if the table
    is being altered in play: if, for instance, the player is naming things.

\block{verify}|0OP:189  D  3  verify          <label>|
    \continue
    Verification counts a (two byte, unsigned) checksum of the
    file from |$0040| onwards (by taking the sum of the values of each byte
    in the file, modulo |$10000|) and compares this against the value in the
    game header, branching if the two values agree.  (Early Version 3 games
    do not have the necessary checksums to make this possible.)
    \continue
    The interpreter may stop calculating when the file length (as given in
    the header) is reached.  It is legal for the file to contain more bytes
    than this, but if so the extra bytes must all be 0, which would contribute
    nothing the the checksum anyway.  (Some story files are padded
    out to an exact number of virtual-memory pages using 0s.)

\block{"vje"}Internal Inform name for the variable-length form of |je| (for
    compiling conditions such as |a==1 or 2 or 4|).

\block{window\_size}|EXT:273 11  6  window_size     window y x|
    \continue
    Change size of window in pixels.  (Does not change the
    current display.)

\block{window\_style}|EXT:274 12  6  window_style    window flags operation|
    \continue
    Changes attributes for a given window.  A bitmap of
    attributes is given, in which the bits are: 1 -- keep text within margins,
    2 -- scroll when at bottom, 3 -- copy text to output stream 2 (the printer),
    4 -- buffer text to word-wrap it between the margins of the window.
    \continue
    The operation, by default, is 0, meaning ``set to these settings".  1 means
    ``set the bits supplied".  2 means ``clear the ones supplied", and 3 means
    ``reverse the bits supplied" (i.e. eXclusive OR).

\newpage

\specs{16}{Font 3 and character graphics}
\sp{1} The following table of $8\times 8$ bitmaps gives a suitable appearance
for font 3.  The font must have a fixed pitch and characters must be printed
immediately next to each other in all four directions.
\orm\beginstt
 32( ):  76543210   33(!):  76543210   34("):  76543210   35(#):  76543210
        0                  0                  0                  0       #
        1                  1                  1                  1      # 
        2                  2  #               2    #             2     #  
        3                  3 ##               3    ##            3    #   
        4                  4#######           4#######           4   #    
        5                  5 ##               5    ##            5  #     
        6                  6  #               6    #             6 #      
        7                  7                  7                  7#       
 36($):  76543210   37(%):  76543210   38(&):  76543210   39('):  76543210
        0#                 0                  0                  0        
        1 #                1                  1                  1        
        2  #               2                  2                  2        
        3   #              3                  3                  3########
        4    #             4                  4########          4        
        5     #            5                  5                  5        
        6      #           6                  6                  6        
        7       #          7                  7                  7        
 40(():  76543210   41()):  76543210   42(*):  76543210   43(+):  76543210
        0    #             0   #              0    #             0        
        1    #             1   #              1    #             1        
        2    #             2   #              2    #             2        
        3    #             3   #              3########          3        
        4    #             4   #              4                  4########
        5    #             5   #              5                  5    #   
        6    #             6   #              6                  6    #   
        7    #             7   #              7                  7    #   
 44(,):  76543210   45(-):  76543210   46(.):  76543210   47(/):  76543210
        0    #             0   #              0   #              0        
        1    #             1   #              1   #              1        
        2    #             2   #              2   #              2        
        3    #             3   #              3   #              3   #####
        4    ####          4####              4   #####          4   #    
        5    #             5   #              5                  5   #    
        6    #             6   #              6                  6   #    
        7    #             7   #              7                  7   #    
\endtt\vfill\eject
\orm\beginstt
 48(0):  76543210   49(1):  76543210   50(2):  76543210   51(3):  76543210
        0                  0    #             0   #              0#       
        1                  1    #             1   #              1 #      
        2                  2    #             2   #              2  #     
        3#####             3    #             3   #              3   #####
        4    #             4#####             4   #####          4   #    
        5    #             5                  5  #               5   #    
        6    #             6                  6 #                6   #    
        7    #             7                  7#                 7   #    
 52(4):  76543210   53(5):  76543210   54(6):  76543210   55(7):  76543210
        0       #          0    #             0########          0########
        1      #           1    #             1########          1########
        2     #            2    #             2########          2########
        3#####             3    #             3########          3########
        4    #             4#####             4########          4########
        5    #             5     #            5########          5        
        6    #             6      #           6########          6        
        7    #             7       #          7########          7        
 56(8):  76543210   57(9):  76543210   58(:):  76543210   59(;):  76543210
        0                  0#####             0   #####          0    #   
        1                  1#####             1   #####          1    #   
        2                  2#####             2   #####          2    #   
        3########          3#####             3   #####          3########
        4########          4#####             4   #####          4########
        5########          5#####             5   #####          5########
        6########          6#####             6   #####          6########
        7########          7#####             7   #####          7########
 60(<):  76543210   61(=):  76543210   62(>):  76543210   63(?):  76543210
        0########          0#####             0   #####          0   #####
        1########          1#####             1   #####          1   #####
        2########          2#####             2   #####          2   #####
        3########          3#####             3   #####          3   #####
        4########          4########          4########          4   #####
        5    #             5#####             5   #####          5        
        6    #             6#####             6   #####          6        
        7    #             7#####             7   #####          7        
 64(@):  76543210   65(A):  76543210   66(B):  76543210   67(C):  76543210
        0                  0                  0#####             0   #####
        1                  1                  1#####             1   #####
        2                  2                  2#####             2   #####
        3   #####          3#####             3#####             3   #####
        4   #####          4#####             4#####             4   #####
        5   #####          5#####             5                  5  #     
        6   #####          6#####             6                  6 #      
        7   #####          7#####             7                  7#       
\endtt\vfill\eject
\orm\beginstt
 68(D):  76543210   69(E):  76543210   70(F):  76543210   71(G):  76543210
        0#                 0       #          0#####             0       #
        1 #                1      #           1#####             1        
        2  #               2     #            2#####             2        
        3   #####          3#####             3#####             3        
        4   #####          4#####             4#####             4        
        5   #####          5#####             5     #            5        
        6   #####          6#####             6      #           6        
        7   #####          7#####             7       #          7        
 72(H):  76543210   73(I):  76543210   74(J):  76543210   75(K):  76543210
        0                  0                  0#                 0########
        1                  1                  1                  1        
        2                  2                  2                  2        
        3                  3                  3                  3        
        4                  4                  4                  4        
        5                  5                  5                  5        
        6                  6                  6                  6        
        7       #          7#                 7                  7        
 76(L):  76543210   77(M):  76543210   78(N):  76543210   79(O):  76543210
        0                  0#                 0       #          0        
        1                  1#                 1       #          1########
        2                  2#                 2       #          2        
        3                  3#                 3       #          3        
        4                  4#                 4       #          4        
        5                  5#                 5       #          5        
        6                  6#                 6       #          6########
        7########          7#                 7       #          7        
 80(P):  76543210   81(Q):  76543210   82(R):  76543210   83(S):  76543210
        0                  0                  0                  0        
        1########          1########          1########          1########
        2#                 2##                2###               2####    
        3#                 3##                3###               3####    
        4#                 4##                4###               4####    
        5#                 5##                5###               5####    
        6########          6########          6########          6########
        7                  7                  7                  7        
 84(T):  76543210   85(U):  76543210   86(V):  76543210   87(W):  76543210
        0                  0                  0                  0        
        1########          1########          1########          1########
        2#####             2######            2#######           2########
        3#####             3######            3#######           3########
        4#####             4######            4#######           4########
        5#####             5######            5#######           5########
        6########          6########          6########          6########
        7                  7                  7                  7        
\endtt\vfill\eject
\orm\beginstt
 88(X):  76543210   89(Y):  76543210   90(Z):  76543210   91([):  76543210
        0                  0                  0#      #          0    #   
        1       #          1#                 1 #    #           1    #   
        2       #          2#                 2  #  #            2    #   
        3       #          3#                 3   ##             3    #   
        4       #          4#                 4   ##             4########
        5       #          5#                 5  #  #            5    #   
        6       #          6#                 6 #    #           6    #   
        7                  7                  7#      #          7    #   
 92(\):  76543210   93(]):  76543210   94(^):  76543210   95(_):  76543210
        0   ##             0   ##             0   ##             0########
        1  ####            1   ##             1  ####            1#      #
        2## ## ##          2   ##             2## ## ##          2#      #
        3   ##             3   ##             3   ##             3#      #
        4   ##             4## ## ##          4## ## ##          4#      #
        5   ##             5  ####            5  ####            5#      #
        6   ##             6   ##             6   ##             6#      #
        7                  7                  7                  7########
 96(`):  76543210   97(a):  76543210   98(b):  76543210   99(c):  76543210
        0  ####            0##   #            0 ##               0   #    
        1 ##  ##           1# # #             1 # #              1   ##   
        2     ##           2#  #              2 #  #             2   # #  
        3    ##            3##                3 ###              3#  #  # 
        4   ##             4# #               4 #  #             4 # #    
        5                  5#  #              5 # #              5  ##    
        6   ##             6#                 6 ##               6   #    
        7                  7                  7                  7        
100(d):  76543210  101(e):  76543210  102(f):  76543210  103(g):  76543210
        0#     #           0#     #           0#  # #            0#     # 
        1##   ##           1##   ##           1# # #             1 #   #  
        2# # # #           2# # # #           2## #              2  # #   
        3#  #  #           3#  #  #           3# #               3   #    
        4# # # #           4#     #           4##                4  # #   
        5##   ##           5#     #           5#                 5 #   #  
        6#     #           6#     #           6#                 6#     # 
        7                  7                  7                  7        
104(h):  76543210  105(i):  76543210  106(j):  76543210  107(k):  76543210
        0##    #           0   #              0   #              0   #    
        1# #   #           1   #              1  ###             1   #    
        2## #  #           2   #              2 # # #            2   #    
        3# # # #           3   #              3#  #  #           3  ###   
        4#  # ##           4   #              4 # # #            4 # # #  
        5#   # #           5   #              5  ###             5#  #  # 
        6#    ##           6   #              6   #              6#  #  # 
        7                  7                  7                  7        
\endtt\vfill\eject
\orm\beginstt
108(l):  76543210  109(m):  76543210  110(n):  76543210  111(o):  76543210
        0   #              0##   ##           0#  #              0##   #  
        1   ##             1# # # #           1 # #              1# # ##  
        2   # #            2#  #  #           2  ###             2## # #  
        3   #  #           3# # # #           3   # #            3# # #   
        4   #              4##   ##           4   #  #           4#  #    
        5   #              5#     #           5   #              5#       
        6   #              6#     #           6   #              6#       
        7                  7                  7                  7        
112(p):  76543210  113(q):  76543210  114(r):  76543210  115(s):  76543210
        0#                 0 #                0 ##               0 #      
        1#                 1 #                1 # #              1 #   #  
        2#                 2 #                2 #  #             2 #  ##  
        3#  #              3 ####             3 # #              3 # # #  
        4# # #             4 #   #            4 ##               4 ##  #  
        5##   #            5 #   #            5 # #              5 #   #  
        6#     #           6 #   #            6 #  #             6     #  
        7                  7                  7                  7        
116(t):  76543210  117(u):  76543210  118(v):  76543210  119(w):  76543210
        0   #              0 ##               0   #              0 ##     
        1  ###             1 # #              1# ### #           1 # #    
        2 # # #            2 #  #             2 # # #            2 #  #   
        3#  #  #           3 #   #            3   #              3 # #    
        4   #              4 #   #            4   #              4 ##     
        5   #              5 #   #            5   #              5 #      
        6   #              6 #   #            6   #              6 #      
        7                  7                  7                  7        
120(x):  76543210  121(y):  76543210  122(z):  76543210  123({):  76543210
        0#  #  #           0###               0   #              0###  ###
        1 # # #            1## #              1  # #             1##    ##
        2  ###             2# # #             2 #   #            2  #  #  
        3   #              3#  # #            3  # #             3###  ###
        4   #              4#  ## #           4   #              4###  ###
        5   #              5#  # ##           5  # #             5###  ###
        6   #              6#  #  #           6 #   #            6###  ###
        7                  7                  7                  7########
124( ):  76543210  125(}):  76543210  126(~):  76543210
        0###  ###          0###  ###          0##    ##
        1###  ###          1##    ##          1#  ##  #
        2###  ###          2  #  #            2#####  #
        3###  ###          3###  ###          3####  ##
        4  #  #            4  #  #            4###  ###
        5##    ##          5##    ##          5########
        6###  ###          6###  ###          6###  ###
        7########          7########          7########
\endtt
\vfill\eject

\remarks
The short Inform program ``fonts.inf'' may be useful for testing the fonts
produced by an interpreter (at least in their appearance on the upper
window).

Two different versions of font 3 were supplied by Infocom, which we shall
call the Amiga and PC forms (the Atari form is the same as for the PC).  The
arrow shape differed slightly and so did the rune alphabet.  (A game can
rely only on the 26 letters each having its own rune.)  Each was an attempt
to map the late Anglian (``futhorc'') runic alphabet, which has 33
characters, onto our Latin alphabet.  The drawings above are from the Amiga
set.

Most of the mappings are straightforward (e.g., Latin A maps to Anglian a),
except that: Latin C is mapped to Anglian eo; K to ``other k'' (previously a
z sound); Q to Anglian k (the same rune as c); V to ea; X to z and Z to oe. 
The PC runes differ as follows: G has an ornamental circle making it more
look like ``other z''; K maps to Anglian k (or c); Q is an Anglian ea (which
resembles the late Anglian q); V is an oe; X is an ``other k'' and Z is a
symbol Infocom seem to have invented themselves.  (Though less well drawn
the PC runes arguably have a better sound-mapping.)

The font behaviour of `Beyond Zork' is rather complicated and depends on
the interpreter number if finds in the header (see \S 11).  If this is 1
(for Infocom's own mainframe) it asks whether the player has a VT220
terminal (a Digital terminal capable of character graphics) and, if so,
always uses font 3 (whatever |set_font| returns, whatever the interpreter
did with bit 3 of `Flags 2').  Here Infocom were clearly violating their
own specification for in-house convenience.

`Beyond Zork' story files initially have bit 3 of `Flags 2' set, and
for higher interpreter numbers (i.e. for Infocom's released interpreters)
the game does avoid font 3 if the interpreter has cleared this bit again.

If interpreter number 6 (for MS-DOS, i.e., an IBM PC) clears the bit,
though, `BZ' does something redundant: it uses |set_font 3|
anyway (ignoring the return code, which should be always be a refusal)
and then prints using IBM PC graphics codes.  This is a problem for
|Zip|, since many non-IBM ports of it still have interpreter number 6.
|Zip| therefore has to convert these IBM PC codes back into ASCII,
which it does as follows:
\beginstt
 179 becomes a vertical stroke (ASCII 124)
 186         a hash (ASCII 35)
 196         a minus sign (ASCII 45)
 205         an equals sign (ASCII 61)
 all others in the range 179 <= c <= 218 become a plus sign (ASCII 43)
\endtt
`BZ' treats interpreter number 8 (for the Commodore 64) similarly, using
various Commodore character codes if it can't use font 3.  Formally,
the use of these machine-dependent character codes is a violation of
this document's specification.  (So to run a Beyond Zork correctly,
the interpreter should either: (i) not number itself 6 or 8, or
(ii) provide font 3, or (iii) number itself 6 but use the above
translation.)

The ``COLOR'' command in `BZ' (typed at the keyboard) also behaves
differently depending on the interpreter number, which is legal behaviour
and has no impact on the specification.
\tenpoint\newpage

\section{A}{Error messages and debugging}

Older interpreters, such as |ITF|, are extremely curt when an error condition
is reached (for example, an illegal opcode).  Such a thing could only then
arise as a result of a bug elsewhere in the interpreter, so it was
understandable that no effort went into error messages.

In debugging Inform games, though, many error conditions can arise and it is
extremely helpful to report these as fully as possible.  These include:
\item{1.} An illegal opcode being hit;
\item{2.} Nonsense operands (such as reference to non-existent local
variables);
\item{3.} A call to what can't be a routine (because the initial byte is not
between 0 and 15);
\item{4.} A jump or call to an address beyond the size of the story file;
\item{5.} An attempt to |print_object| an object which doesn't exist
(especially on the status line in V3 games);
\item{6.} Division by zero.
\noindent The player sometimes then has the annoying task of working out
where the error took place in source code.  Providing a stack back-trace
would be a help.

In addition, an interpreter might provide options for keeping track of
maximum stack usage and the typical number of opcodes executed between
each read from the keyboard.  (But watching these is a time-wasting
activity, so they should be options.)

Finally, infinite loops fairly often happen, as in any programming
language.  On a system without pre-emptive multi-tasking, this may lock
up the whole machine, as the usual way that porters implement multi-tasking
is to return control to the host operating system only when the keyboard
is read.  This can be avoided by providing a point in the code which
could return control to the OS from time to time: on an Acorn
Archimedes, for instance, passing control out of |Zip| once every
2000 instructions has solved the problem without noticeably slowing
game play.

\section{B}{Conventional contents of the header}

The header table in \S 11 details everything the interpreter needs to know
about the header's contents.  A few other slots in the header are meaningful
but only by convention (since existing Infocom and Inform games write them). 
These additional slots are described here.

As in \S 11, ``Hex'' means the address, in hexadecimal; ``V'' the
earliest version in which the feature appeared; ``Dyn'' means that the byte
or bit may legally be changed by the game during play (no others may legally
be changed by the game); ``Int'' means that the interpreter may (in some
cases must) do so.
\midinsert\smallskip\hrule\smallskip\beginlines
| Hex  V  Dyn Int  Contents|
\endlines\smallskip\hrule\smallskip\beginlines
|  1   1           Flags 1:|
|      .3      *     Bit 2    (unused but set in V3?)|
|      .3      *         3    The legendary "Tandy" bit (see note)|
|  2   1           Release number (word)|
| 10   1   *       Flags 2:|
|      .3            Bit 4    Set in the Amiga version of The Lurking Horror|
|                               so presumably to do with sound effects?|
|      .?  ?   *        10    Possibly set by interpreter to indicate an error|
|                               with the printer during transcription|
| 12   2           Serial code (six characters of ASCII)|
|      3           Serial number (ASCII for the compilation date in|
|                                 the form YYMMDD)|
| 38   6       *   8 bytes of ASCII: the player's user-name on Infocom's|
|                    own mainframe, useful to identify which person played|
|                    a particular saved-game|
\endlines\smallskip\hrule\endinsert

1. In Versions 1 to 3, bits 0 and 7 of `Flags 1' are unused.  In later
Versions, bits 0, 6 and 7 are unused.  In `Flags 2', bits 9 and 11-15 are
unused.  Infocom used up almost the whole header: only the bytes at |$32|
and |$33| are unused in any Version, and those are now allocated for
standard interpreters to give their Revision numbers.

2. Some early Infocom games were sold by the Tandy Corporation, who
seem to have been sensitive souls.  `Zork I' pretends not to have sequels
if it finds the Tandy bit set.  And to quote Paul David Doherty:
\quote
   In `The Witness', the Tandy Flag can be set while playing the game,
   by typing |$DB| and then |$TA|.  If it is set, some of the prose will be
   less offensive. For example, ``private dicks" become ``private eyes",
   ``bastards" are only ``idiots", and all references to ``slanteyes" and
   ``necrophilia" are removed.
\endquote
We live in an age of censorship.

3. For comment on interpreter numbers, see \S 11. Infocom's own interpreters
were generally rewritten for each of versions 3 to 6.  For instance,
interpreters known to have been shipped with the Macintosh gave version
letters B, C, G, I (Version 3), E, H, I (Version 4), A, B, C (Version 5) and
finally 6.1 for Version 6.  (Version 6 interpreters seem to have version
numbers rather than letters.)  See the ``Infocom fact sheet'' for fuller
details.

\newpage

\section{C}{Resources available}

\quote
...the dead hand of the academy had yet to stifle the unbridled
enthusiasms of a small band of amateurs in Europe and America.
\poemby{Michael D. Coe}{Breaking the Maya Code}

The resources below are all available from the |if-archive| at the
anonymous FTP site |ftp.gmd.de| in Germany, maintained by Volker
Blasius.

\subtitle{Interpreters}
       
Six interpreters are publically available, of which two are in widespread
use:
\item{1.} |Zip|, by Mark Howell (1991-), is currently the most accurate
interpreter across Versions 1 to 5.  It is fast and has reasonably good
error reportage.
\item{2.} The |InfoTaskForce| (or |ITF|) interpreter (1987-92) is almost as
good, but slower and less accurate on some Version 5 features.  It is no
longer maintained and the final version was 4.01.  Various patches have
been made to improve ports of |ITF|: for instance, Bryan Scattergood's
Psion and Archimedes interpreter is much more accurate.
\par\noindent
The other four are obsolescent or have yet to be widely used:
\item{3.} |Pinfocom| (1992), derived from an early form of |ITF|, and
released by Paul Smith as a Version 3 (only) interpreter; final version 3.0.
\item{4.} |Zmachine| (1988-90), by Matthias Pfaller: briefly in limited
circulation (again, for Version 3 only).
\item{5.} |ZIPDebug| (1991-3), by Frank Lancaster, supporting Versions 1
to 5 and offering some debugger facilities.
\item{6.} |Zterp| (1992), by Charles M. Hannum, for Versions 3 to 5:
reputedly very fast.
\par\noindent
Currently we lack a comprehensive Version 6 interpreter.  It is hoped that
|Zip| will eventually support Version 6 as well.

\subtitle{Compilers}

Infocom's original compiler |Zilch| no longer exists: nor is any of its
language, |ZIL|, documented anywhere (though this is similar to |MDL|, which
is documented): nor is any of Infocom's source code in the public domain
(though a fragment or two by Stu Galley has been circulated a little).

Inform is the only other compiler to have existed.  It is freeware and
comes with full documentation (of which this document is a part).

\subtitle{Debugger}

An enhanced version of |Zip|, a source-level debugger for
Inform games called |Infix|, can be obtained in test form from Dilip
Sequeira.

\subtitle{Utility programs}

Mark Howell has written a toolkit of utility programs (1991-5; sometimes
called |Ztools|), which includes:
\item{1.} |Txd|, a disassembler for Versions 1 to 6.  (Uses the
same opcode names as Inform and this document, and has an option to
disassemble in Inform assembly-language syntax.)
\item{2.} |Infodump|, capable of printing the header information,
object tree (with properties and attributes), dictionary and grammar
tables of a Version 1 to 5 game.  (Also has some ability to print the
parsing tables used by the Inform parser; and decodes all but the
parsing tables for Version 6 games too.)
\item{3.} |Pix2gif|, for converting Version 6 picture data
to GIF files.
\item{4.} |Check|, for verifying story files.

\par\noindent
|Infodump| largely supersedes Mike Threepoint's vocabulary dumper
|Zorkword| (1991-2), which was important in its day (and which the
author found extremely helpful when writing Inform 1).

\subtitle{Story files}

\item{1.} Many Inform-compiled story files are publically available:
games such as `Curses', `Christminster', `Theatre', `Busted', `Balances',
`Advent', `Adventureland' and so on.
\item{2.} A few Infocom story files are public, notably two 4-in-1 sample
games (released for advertising purposes) and `Minizork' (a heavily
abbreviated form of Zork I released with a Commodore magazine).
\item{3.} Almost all Infocom's games remain commercially available in
anthologies published by Activision.  Copyright resides in them and they
should not available by FTP from any site.
\item{4.} A few other Infocom story files have existed but are neither
on sale nor released from copyright: this applies to several of the
Version 6 games, `Leather Goddesses of Phobos' and ephemera such as
beta-test versions which have somehow passed into private circulation.

\par\noindent
Most of the Infocom games exist in several different releases, and some
were written for one Version and then ported to later ones.  `Zork I', for
instance, has at least 11 releases, 2 early, 8 in Version 3
(with release numbers between 5 to 88 in chronological order) and one in
Version 5 (release 52 -- the releases go back to 1 when the version changes).

Version 1 and 2 games are extinct, though there are a few fossils
in the hands of collectors.

\subtitle{Documents}

The definitive guide to all Infocom story files known to exist, and an
indispensable reference for anyone interested in Infocom, is Paul David
Doherty's ``fact sheet'' file, which is regularly updated, concise and
precise.  This supersedes Paul Smith's ``Infocom Game Information'' file.

Stefan Jokisch has written a brief specification of Infocom-format
sound effects files.

The {\sl Inform Technical Manual} documents the format of parsing tables
used in Inform games.

Most of the contents of the original Infocom game manuals are still on
sale with the games themselves: the ``samplers'' (sample transcripts of
play) are not, but an archive of them is publically available.  So is
an interesting historical archive of magazine articles concerning
Infocom, and articles from Infocom's own publicity magazine.


\section{D}{A short history of the Z-machine}

Infocom made six main Versions of the Z-machine and several minor variant
forms.  These are recognisably similar but with labyrinthine differences,
like different archaic dialects of the same language.  (The archaeological
record stops sharply in 1989 when the civilisation in question collapsed.)

Broadly, these fall into two groups: early (Versions 1 to 3) and late
(4 to 6).  More fully:
\smallskip
\settabs\+\indent Version 1\quad&\cr
\+ Version 1 & Early Apple ][ and TRS-80 Model I games\cr
\+ Version 2 & Early Apple ][ and TRS-80 Model I games\cr
\smallskip
\+ Version 3 & ``Standard'' series games\cr
\+ Version 4 & ``Plus'' series games\cr
\+ Version 5 & ``Advanced" series games, or, as the marketing division would\cr
\+           & have it, ``Solid Gold Interactive Fiction" -- a reference to\cr
\+           & the colour (though not composition) of the boxes they came in\cr
\smallskip
\+ Version 6 & Later games with graphics, mouse support, etc.\cr
\smallskip
\noindent 
Infocom called their own interpreters ZIP (versions 1 to 3), EZIP/LZIP
(V4), XZIP (V5) and YZIP (V6).  They speculated on the possibility of an
interpreter capable of running all Versions, but never published one.
\bigskip

The original purpose of the Z-machine was simply to implement as much as
possible of the mainframe game ``Zork'' on the first popular wave of home
computers.

(Apparently ``zork" was a nonsense word used at MIT for the current
uninstalled program in progress, and stuck.  Just as this document uses the
term ``Z-machine" for both the machine and its loaded program (which is also
sometimes called the ``story file''), so ZIP (Zork Implementation Program)
was used to mean either the interpreter or the object code it interpreted. 
Code was written in ZIL (Zork Implementation Language), which was derived
from MDL (informally called ``muddle"), a particularly unhelpful form of
LISP.  It was then compiled by ZILCH to assembly code which was passed to
ZAP to make the ZIP.)

The Z-machine as originally constructed was surprisingly similar to that in
use today.  Version 1 (by Joel Berez and Marc Blank, in Autumn 1979)
contained essentially all of the main architecture: the header, the memory
divided into three, the variables and stack, the object tree, the
dictionary, the instruction format.  It used ``shift lock''
characters (a text compression trick which did not survive, though it was
more efficient on long sequences of capital letters or punctuation
characters than the technique which replaced it).  The first micro
interpreters were for the TRS-80 Model I (by Scott Cutler) and the Apple II
(by Bruce K. Daniels).  (A TRS-80 Model II interpreter was written but never
actually shipped.)

Version 2 was only a minor enhancement.  Abbreviations (used to help
text compression) appeared, but only in one 32-word bank, and the
six-digit serial number appeared in the header, though it wasn't always the
date in those days: Release 7 of `Zork II', for instance, is numbered
|UG3AU5|.  (Other bizarre serial numbers, such as |000000|, appear on fakes
or beta-test releases.)

In Version 3, the text encoding alphabets changed again, and the old ``shift
lock'' codes were dropped in favour of expanding the abbreviations bank to 96
entries.  The ``verify" opcode and checksums appeared; and a new opcode to
reprint the status line at the top of the screen was introduced.
(Previously, this had been updated only when input was taken from the
keyboard.)  The earliest Version 3 releases (`Deadline', then reissues of
`Zork I' and `II') were in March and April 1982; the last (the `Minizork', a
cassette-based Commodore-64 sample of `Zork') was in November 1987.

The idea of widespread portability finally came of age as (between 1982 and
1985) interpreters were developed for the Atari 400/800, CP/M, the IBM PC,
the TRS-80 Model III, the NEC APC, the DEC Rainbow, the Commodore 64, the TI
Professional, the DECmate, the Tandy-2000, the Kaypro II, the Osborne 1,
MS-DOS, the TI 99/4a, the Apple Macintosh, the Epson QX-10, the Apricot, the
Atari ST and the Amiga.  Infocom's middle period coincided with the bubble
in home computers, before the market collapsed to its present apparently
stable state (in which IBM and Apple share almost the entire market), and
the Z-machine's portability gave Infocom a unique advantage over its
competitors.  Also, it was an expertly marketed quality brand at a time when
standards of workmanship were very variable; and text-only games did not
seem so dull at a time when graphics were on the whole crude and slow. These
factors combined to give Infocom considerable (though never enormous)
commercial success.

By 1982, then, the Z-machine had stabilised to a clean design which was to
remain in use for six years.  It was very portable, contained everything
reasonably necessary and most of its complications were badly-needed space
optimisations.  (Although Version 3 can fit 128K of story file, the
practical limit in 1982-4 was about 110K, that being the typical disc
capacity on target machines.)  The ZAP assembler was cleverly written to
exploit these optimisations, though the Zilch compiler's code generator was
much less efficient.  (Interestingly, Infocom did not develop any generic
central library, and Infocom's authors worked fairly independently of each
other: each new game would inherit a small core of code from a previous one,
but this would make up only about 10K of code (about a third of the size of
the Inform library) and would end up being hacked about to suit the new
game.  Without a central library, Infocom games waste a fair amount of space
in duplicating code for routine operations many times over.  For this
reason, Inform games tend to squash appreciably more design into the
format.)

``Verify'' and checksum data were quickly introduced.  However, the first
serious variant on Version 3 was made in 1984 when a primitive form of
screen-splitting was invented to give `Seastalker' a sonar display.  This
design (perhaps accidentally) became the foundation for the graphics systems
of later versions.

Much later (in 1987) sound effects were added to Version 3 for `The Lurking
Horror', though by that time it was really a Version 5 feature being
passed down to the old model (and only to the Amiga interpreter in any case).
(`TLH' is contemporaneous with `Sherlock' (in Version 5), the only other game
to actually use the sound effects features.)
\medskip

During 1983-5, Infocom poured resources into an ambitious pet project of its
founders: `Cornerstone', a database which used some of the same portable
virtual machine ideas as the Z-machine.  The business market, however, was
not nearly as diverse as the home computer market: `Cornerstone' probably was
the best database available on the Atari ST, but it made no impression on
the IBM PC market.  The result was a commercial failure which compounded the
company's over-expansion problems (driving it into a merger with
Activision), though it certainly did not destroy Infocom's viability.
\medskip

By 1985, Infocom had begun to write interpreters in C for the sake of
portability (previously, a different assembly-language program had to be
maintained for every model of computer).  The main motivation to keep the
format stable was therefore largely removed: it became possible to upgrade
the Z-machine for every new game, if need be.

There were two basic pressures for change.  One was that home computers were
larger, and several fundamental restrictions (the game size being only 128K,
the number of objects only 255, the attributes only 32, the properties only
31) were beginning to bite.  The other was the drive for more gimmicks -
character graphics, flashier status lines, sound effects, different
typefaces, and so on.  The former led to logical, easy to understand
structural changes in the machine (designed by Marc Blank).  The latter, in
contrast, made a mess of the system of opcodes (designed by committee).

More does not mean better (halving the price of paper does not double the
quality of the novel).  The relieving of size restrictions only increased
design time -- or endangered the quality of the designs being produced.  The
Version 3 games have a spare, concise literary style which is absent from
the later games.  (But Inform authors have certainly found Version 3
slightly too small for comfort, and it's useful to be able to spill over its
boundaries.)

In August the first Version 4 game (`A Mind Forever Voyaging') reached
production.  Opinions vary as to whether it was brilliant or awful, but it
was certainly a departure (and could not have been written under Version 3). 
In retrospect there is no doubt about `Trinity', now generally considered
the finest game written: it had previously been shelved as too ambitious
for the Version 3 format.  Still, most of the new 1985/6 games remained in
Version 3: there were still plenty of 8-bit home computers around which were
too small for Version 4 games.  Despite critical acclaim, the new games
consequently did not sell as well.  (Brian Moriarty commented that `Trinity'
``sold tolerably well. Better than we'd hoped.''  But his previous game, the
more modest `Wishbringer', had sold rather better.)

Version 5 games began to appear in September 1987 with `Beyond Zork' and
`Border Zone'.  Both of these games needed new features -- character graphics
run wild in the case of the former, and real-time keyboard interaction in
the latter.  The number of opcodes grew ever faster as a result.

Although five old games were re-released in Version 5 editions (with an
in-game hints system added, and benefiting from 9-letter word dictionaries,
but otherwise as written), the direction was all too clearly away from the
old text game into graphics: `Beyond Zork' can look like a parody of an
early mainframe maze game, for instance.  Version 6 completed the process
during something of a hiatus in 1988, after which the last few
increasingly-unrecognisable Infocom games appeared: `Zork Zero', `Shogun',
`Journey' and `Arthur'.

It would be wrong, though, to suggest that Infocom regarded text and
graphics as incompatible opposites.  Infocom had never been puritanically
opposed to graphics --

\quote We have nothing against graphics per se.  However, given the quality of 
  graphics currently available on home computers, we would rather use that
  disk space for additional puzzles and richer descriptions.
\quoteby{The New Zork Times (Spring 1984)}

\noindent (and, after all, the same author wrote both `Trinity' and `Beyond
Zork').  Although the old Infocom parser was considered to have passed its
sell-by date, Version 6 did not drop textual input in favour of some inane
point-and-click interface.  Instead, an entirely new parser was devised from
scratch (``using the theory of computational linguistics'', according to a
puff by Stu Galley).

Infocom gradually ceased to exist during 1987-9 as its financial problems
grew.  But its products were increasingly regarded as an anachronism and
most of its staff had left since the middle years: if Infocom had not
finally been wound up, whether it would have continued to release text games
of the classical style is arguable.

\medskip
Two new formats, versions 7 and 8, have recently been devised to cope with
large Inform games.

\section{E}{A few statistics}

\quote
LORD DIMWIT FLATHEAD:  ``It must have two hundred thousand rooms, four
million takeable objects, and understand a vocabulary of every single word
ever spoken in every language ever invented.''
\quoteby{The New Zork Times (Winter 1984)}

To give some idea of the sizes found in typical story files, here are a few
statistics, mostly gathered by Paul David Doherty, whose ``Infocom fact
sheet" file is the definitive reference.

\medskip
(i) {\sl Length}\quad
  The shortest files are those dating from the time of the `Zork'
  trilogy, at about 85K; middle-period Version 3 games are typically 105K,
  and only the latest use the full memory map.  In Versions 4 and 5, only
  `Trinity', `A Mind Forever Voyaging' and `Beyond Zork' use the full 256K.
  `Border Zone' and `Sherlock', for instance, are about 180K.  (The author's
  short story `Balances' is about 50K, an edition of `Adventure' takes 80K,
  and `Curses' takes 256K (it's padded out to the maximum size with
  background information; the actual game comprises only about 245K).  Under
  Inform, the library occupies about 35K regardless of the size of game.)


\medskip
(ii) {\sl Code size}\quad
  `Zork I' uses only about 5500 opcodes, but the number rises
  steeply with later games; `Hollywood Hijinx' has 10355 and, e.g.
  `Moonmist' has 15900 (both these being Version 3).  Against this, `A Mind
  Forever Voyaging' has only 18700, and only `Trinity' and `Beyond Zork'
  reach 32000 or so.  (Inform games are more efficiently compiled and make
  better use of common code -- the library -- so perform much better here:
  the old Version 3, release 10 of `Curses' (128K long, and a larger game
  than any Infocom Version 3 game) has only 6720 opcodes.)

\medskip
(iii) {\sl Objects and rooms}\quad
  This varies greatly with the style of game.
  `Zork I' has 110 rooms and 60 takeable objects, but several quite
  complex games have as few as 30 rooms (the mysteries, or `Hitch-hikers'). 
  The average for Version 3 games is 69 rooms, 39 takeable objects.

  `A Mind Forever Voyaging' contains many rooms (178) but few objects (30). 
  `Trinity', a more typical style of game, contains 134 rooms and 49
  objects: the Version 5 `Curses' has a few more of each.  Of the Version 6
  games, only `Zork Zero' scores highly here, with 215 rooms and 106
  objects.  The average for Version 4/5 games is 105 rooms and 54 objects.

  The total number of objects tends to be close to the limit of 255 in
  Version 3 games.  `Curses' contains 508.


\medskip
(iv) {\sl Dictionary}\quad  Early games such as `Zork I' know about 600 words, but
  again this rises steeply to about 1000 even in Version 3.
  Later games know 1569 (`Beyond Zork') to the record, 2120 (`Trinity').
  (This is achieved by heroic inclusion of unlikely synonyms: e.g. the
  Japanese lady with the umbrella can be called WOMAN, LADY, CRONE,
  MADAM, MADAME, MATRON, DAME or FACE with any of the adjectives
  OLD, AGED, ANCIENT, JAP, JAPANESE, ORIENTAL or YELLOW.)
  Version 6 games have smaller dictionaries.  So has `Curses', at 1364.

\section{F}{Implementing the new Versions 7 and 8}

At present, two ``modern'' formats have been created: Inform 5.5 has the
ability to compile to them, but no such games prior to 1995 exist.
 
These new versions exist to remove the chief restriction on version-5
games: the total memory map limit of 256K.  (Although V6 removes this
restriction, full interpretation of V6 is much harder than V5 and
the extra complexity is unnecessary for text games.  New formats thus
seem preferable to use of V6, though Inform can produce V6 too.)

Both versions are {\sl identical to V5 except} for the way packed addresses
are decoded.  Let $R_O$ be the routines offset, and $S_O$
the strings offset.  Then the byte address of packed address $P$ is presently
given by:
$$ \cases { 2P & versions 1, 2 and 3\cr
            4P & versions 4 and 5\cr
            4(P+R_O) {\rm~or~} 4(P+S_O) & version 6 routine calls/{\tt print\_paddr}\cr
} $$
and the new versions translate instead by:
$$ \cases { 4(P+R_O) {\rm~or~} 4(P+S_O) & version 7 routine calls/{\tt print\_paddr}\cr
            8P & version 8\cr} $$

The reason for two new formats is that it offers two chances to
extend existing interpreters (one of which may be much less trouble
than the other).  However, the preferred large format is V8, for
which the modification required to the |Zip| interpreter is one
single line:
insert
\beginlines
|    if (h_type == 8) { h_type=V5; story_scaler = 8; story_shift = 3; }|
\endlines
into the |configure()| routine.


\newpage
\pageno=1\titletrue

\centerline{\bigfont The Specification of the Z-Machine}
\vskip 0.3in
\centerline{\medfont and Inform assembly language}
\vskip 0.3in
\centerline{\sl Standard 0.2: 15th November 1995}
\vskip 0.5in 

\immediate\closeout\conts
\sli{}{Preface}{2}
\sli{1}{The memory map}{5}
\sli{2}{Numbers and arithmetic}{7}
\sli{3}{How text is encoded and printed}{8}
\sli{4}{How instructions are encoded}{12}
\sli{5}{How routines are encoded}{16}
\sli{6}{The game state: storage and routine calls}{16}
\sli{7}{Output streams and file handling}{19}
\sli{8}{The screen model}{21}
\sli{9}{Sound effects}{28}
\sli{10}{Input streams and devices}{30}
\sli{11}{The format of the header}{33}
\sli{12}{The object table}{35}
\sli{13}{The dictionary and lexical analysis}{37}
\sli{14}{Complete table of opcodes}{38}
\sli{15}{Dictionary of opcodes}{44}
\sli{16}{Font 3 and character graphics}{58}
\sli{A}{Error messages and debugging}{64}
\sli{B}{Conventional contents of the header}{64}
\sli{C}{Resources available}{66}
\sli{D}{A short history of the Z-machine}{68}
\sli{E}{A few statistics}{71}
\sli{F}{Implementing the new Versions 7 and 8}{72}

\bigskip
\noindent This is a consultation document: it will become Standard 1.0
early in the New Year after any further comments, corrections and requests
for clarification have been dealt with.
\end

% -------------------------------------------------------------------------

% Inform test files to cut out and collect:

! -------------------------------------------------------------------------
!  Fonts.inf
! -------------------------------------------------------------------------

[ Main; ShowFonts(); quit; ];
[ ShowFonts x;
  @erase_window -1; @split_window 10;
  FontAt(1,0,0); FontAt(2,1,0); FontAt(3,0,1); FontAt(4,1,1);
  @read_char 1 0 0 x;
];
[ FontAt font bx by i j x y;
  @set_window 1; y=1+5*by; x=2+34*bx;
  @set_cursor y x; print "Font ", font;
  @set_font font j; if (j==0) print " unavailable";
  for (i=32:i<127:i++)
  {   y=i/32+1+5*by; x=i%32+2+34*bx; @set_cursor y x;
      if (j==0) print "."; else @print_char i;
  }
  @set_font 1 j; @set_window 0;
];


! -------------------------------------------------------------------------
!  Accents.inf
! -------------------------------------------------------------------------

[ Main;
  ShowAccents(1);
  ShowAccents(4);
  quit;
];
[ ShowAccents font x;
   @set_font font x;
   if (x==0) print_ret "Font ", font, " unavailable.";
   @erase_window -1;
   print "Accented characters test in font ", font, "^^";
   print "Decimal code:  character     name  plain ASCII equivalent^^";
   print "155:   @@155     a-umlaut  ae^";
   print "156:   @@156     o-unlaut  oe^";
   print "157:   @@157     u-umlaut  ue^";
   print "158:   @@158     A-umlaut  Ae^";
   print "159:   @@159     O-umlaut  Oe^";
   print "160:   @@160     U-umlaut  Ue^";
   print "161:   @@161     sz-ligature  ss^";
   print "162:   @@162     quotation mark  << or ~^";
   print "163:   @@163     quotation mark  >> or ~^";
   print "164:   @@164     e-umlaut  e^";
   print "165:   @@165     i-umlaut  i^";
   print "166:   @@166     y-umlaut  y^";
   print "167:   @@167     E-umlaut  E^";
   print "168:   @@168     I-umlaut  I^";
   print "169:   @@169     a-acute  a^";
   print "170:   @@170     e-acute  e^";
   print "171:   @@171     i-acute  i^";
   print "172:   @@172     o-acute  o^";
   print "173:   @@173     u-acute  u^";
   print "174:   @@174     y-acute  y^";
   print "175:   @@175     A-acute  A^";
   print "176:   @@176     E-acute  E^";
   print "177:   @@177     I-acute  I^";
   print "178:   @@178     O-acute  O^";
   print "179:   @@179     U-acute  U^";
   print "180:   @@180     Y-acute  Y^";
   print "181:   @@181     a-grave  a^";
   print "182:   @@182     e-grave  e^";
   print "183:   @@183     i-grave  i^";
   print "184:   @@184     o-grave  o^";
   print "185:   @@185     u-grave  u^";
   print "186:   @@186     A-grave  A^";
   print "187:   @@187     E-grave  E^";
   print "188:   @@188     I-grave  I^";
   print "189:   @@189     O-grave  O^";
   print "190:   @@190     U-grave  U^";
   print "191:   @@191     a-circumflex  a^";
   print "192:   @@192     e-circumflex  e^";
   print "193:   @@193     i-circumflex  i^";
   print "194:   @@194     o-circumflex  o^";
   print "195:   @@195     u-circumflex  u^";
   print "196:   @@196     A-circumflex  A^";
   print "197:   @@197     E-circumflex  E^";
   print "198:   @@198     I-circumflex  I^";
   print "199:   @@199     O-circumflex  O^";
   print "200:   @@200     U-circumflex  U^";
   print "201:   @@201     a-ring  a^";
   print "202:   @@202     A-ring  A^";
   print "203:   @@203     o-slash  o^";
   print "204:   @@204     O-slash  O^";
   print "205:   @@205     a-tilde  a^";
   print "206:   @@206     n-tilde  n^";
   print "207:   @@207     o-tilde  o^";
   print "208:   @@208     A-tilde  A^";
   print "209:   @@209     N-tilde  N^";
   print "210:   @@210     O-tilde  O^";
   print "211:   @@211     ae-ligature  ae^";
   print "212:   @@212     AE-ligature  AE^";
   print "213:   @@213     c-cedilla  c^";
   print "214:   @@214     C-cedilla  C^";
   print "215:   @@215     Icelandic thorn  th^";
   print "216:   @@216     Icelandic eth  th^";
   print "217:   @@217     Icelandic Thorn  Th^";
   print "218:   @@218     Icelandic Eth  Th^";
   print "219:   @@219     pound symbol  L^";
   print "^Please press SPACE.^";
   @read_char 1 0 0 x;
];


! -------------------------------------------------------------------------
!   Inputcodes.inf
! -------------------------------------------------------------------------

[ Main;
  InputCodes();
  quit;
];
[ InputCodes k;
  print "Keyboard input code testing^";
  print "(Press keys to see how they respond, and press SPACE to finish.)^^";
  for (::)
  {   @read_char 1 0 0 k;
      print k, " ";
      switch(k)
      {   ' ': return;
          10, 13: print "return";
          27: print "escape";
          32 to 126: print "character '", (char) k, "'";
          129: print "cursor up";
          130: print "cursor down";
          131: print "cursor left";
          132: print "cursor right";
          133 to 144: print "function key f", k-132;
          145 to 154: print "keypad ", k-144;
          155 to 251: print "accented character '", (char) k, "'";
          252: print "menu click";
          253: print "mouse double-click";
          254: print "mouse click (single or double)";
          default: print "error: code ", k, " should not have been returned";
      }
      new_line;
  }
];


! -------------------------------------------------------------------------
!   Colours.inf
! -------------------------------------------------------------------------

[ Main;
  Colours();
  @quit;
];
[ Colours fg bg;
  print "Colour display testing^";
  if ((1->0)&1 == 0) "Fine: the interpreter says colours are unavailable.";
  print "The interpreter says colours are available.  Let's see...^^";
  for (fg=2:fg<10:fg++)
  {   for (bg=2:bg<10:bg++)
      {   if (fg ~= bg)
          {   @set_colour fg bg;
              print (colourname) fg, " on ", (colourname) bg;
              @set_colour 1 1; new_line;
          }
      }
  }
  new_line;
  for (fg=2:fg<10:fg++)
  {   for (bg=2:bg<10:bg++) { @set_colour fg bg; print "#"; }
      @set_colour 1 1; new_line;
  }
  print "^(Default colours.) Press SPACE to clear.^";
  @read_char 1 0 0 fg;
];
[ Colourname x;
  switch(x)
  {   2: print "black";
      3: print "red";
      4: print "green";
      5: print "yellow";
      6: print "blue";
      7: print "magenta";
      8: print "cyan";
      9: print "white";
  }
];


! -------------------------------------------------------------------------
!   Header.inf
! -------------------------------------------------------------------------

[ Main;
  Header();
  @quit;
];
[ Header flag x y f;
  print "Interpreter declarations:^^";
  flag=1->0;

  print "(In Flags 1...)^";

  #IFV3;
       print "Status line unavailable?", (status) flag&16;
       print "Screen splitting available?", (status) flag&32;
       print "Default font has variable pitch?", (status) flag&64;
  #IFNOT;
       print "Colours available?", (status) flag&1;
       print "Boldface available?", (status) flag&4;
       print "Italic available?", (status) flag&8;
       print "Fixed-pitch font available?", (status) flag&16;
       print "Timed keyboard input available?", (status) flag&128;
  #ENDIF;

  #IFV5;
  print "^(In Flags 2.  The following four questions have meaningful \
         answers only if bits 3, 4, 5 and 7 of Flags 2 were set in \
         advance: to do this, alter the game file by setting byte 16 \
         to 184 and then run it again.)^";
  flag=$10->1;
       print "Pictures available?", (status) flag&8;
       print "UNDO available?", (status) flag&16;
       print "Mouse available?", (status) flag&32;
       print "Sound effects available?", (status) flag&128;
  #ENDIF;

  #IFV5;
  print "^Interpreter (machine) number ", $1e->0,
        " version ", (char) $1f->0, "^";

  print "^Screen height: ";
  x = $20->0; if (x==255) print "infinite^"; else print x, " lines^";

  print "Screen width: ";
  x = $21->0; print x, " fixed-pitch font characters^";

  print "Screen height in units: ", $24-->0, "^";
  print "Screen width in units: ", $22-->0, "^";

  print "Font height in units: ", $26->0, "^";
  print "Font width (of a '0') in units: ", $27->0, "^^";

  if ((1->0)&1 ~= 0)
  {   print "Default background colour: ", (colourname) $2c->0, "^";
      print "Default foreground colour: ", (colourname) $2d->0, "^^";
  }

  for (f=1:f<5:f++)
  {   @set_font f x;
      @set_font 1 y;
      print "Font ", f, " available?", (status) x;
  }
  #ENDIF;

  x=$32-->0;
  print "^Standard specification claimed by the interpreter: ",
        x/256, ".", x%256, "^";

  #IFV5;
  print "^^(Press SPACE to clear.)^";
  @read_char 1 0 0 x;
  #ENDIF;
];
[ Status f;
  if (f==0) "  no"; "  yes";
];
[ Colourname x;
  switch(x)
  {   2: print "black";
      3: print "red";
      4: print "green";
      5: print "yellow";
      6: print "blue";
      7: print "magenta";
      8: print "cyan";
      9: print "white";
  }
];


! -------------------------------------------------------------------------
!   Timedinput.inf
! -------------------------------------------------------------------------

[ Main;
   Timings();
   @quit;
];
Global counter;
[ Timings x;
   print "Testing timed input^^";
   print "If you press no keys, five messages should appear, one second \
          apart.  If you do press a key, the test should finish at once.^^";
   counter=0;
   @read_char 1 10 #r$Interrupt x;
   print "^Test complete.^^";
   print "Now the same test for 1/10th of a second (though probably not all \
          interpreters will be fast enough to make the interval quite that \
          brief).^^";
   counter=0;
   @read_char 1 1 #r$Interrupt x;
   print "^Test complete.^^";
   print "^Please press SPACE.^";
   @read_char 1 0 0 x;
];
[ Interrupt;
   print "  message number ", ++counter, "^";
   if (counter<5) rfalse; rtrue;
];

% -------------------------------------------------------------------------
%  End of specification file
% -------------------------------------------------------------------------